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1. Introduction 



This manual explains how to use the source level debugger, dbx, and 
provides both user and reference information about operating the debugger. 
The debugger works for C, FORTRAN 77, Pascal, assembly language, and 
machine code. 



1.1 Using This Manual 

This book is divided into the chapters listed below. If you're new to dbx, 
you might want to read the entire book. Chapter 2, "Getting Started," 
contains a section describing the few basic commands necessary for 
debugging a simple program. 

For more experienced users looking for specific information, there is an 
overview of what's discussed at the beginning of each chapter. Also, there is 
a list of each command covered in the chapter, its syntax, and a brief 
description of what the command does. For more detailed information, just 
look in that chapter. 
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Overview of This Manual 

The following paragraphs briefly describe the contents of each chapter and 
appendix in this manual. 

Chapter 2, "Getting Started," introduces new users to the debugger. It ^ 

contains a general discussion of the debugging process. This chapter also | 

offers tips for people who are new to source-level debugging. If you're 
experienced at using debuggers, you might want to skip this part. 

Chapter 3, "Running dbx" explains how to run the debugger. In particular, 
it explains how to compile a program for debugging, use the corefile and 
givenfile commands, and how to invoke and quit dbx. 

Chapter 4, "Commands and Expressions," describes dhx commands, 
expression precedence, data types, constants, and registers. 

Chapter 5, "The dbx Monitor," explains how to use history, edit the 
command line, and type multiple commands. 



Chapter 6, "Controlling dbx" explains how to work with variables, how to 
create command aliases, record and playback input and output, invoke a 
shell from dbx, and use the dbx status feature. 

Chapter 7, "Examining Source Programs," explains how to specify source 
directories, move to a specified procedure or source file, list source code, 
search through the source code, call an editor from dbx, print symbolic 
names, and print type declarations. 

Chapter 8, "Controlling Your Program," explains how to run and rerun a 
program, execute single lines of code, return from procedure calls, start at a 
specified line, continue after a breakpoint, and assign values to program 
variables. 

Chapter 9, "Setting Breakpoints," explains how to set and remove 
breakpoints and continue executing a program after a breakpoint. 
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Chapter 10, "Examining Program State," explains how to print stack traces, 
move up and down the activation levels of the stack, print register and 
variable values, and print information about the activation levels in the 
stack. 

Chapter 11, "Debugging at the Machine Level," describes the dbx 
commands for debugging machine code. It also explains how to examine 
memory addresses and disassemble source code. 

Chapter 12, "Multi-Process Debugging," describes the dbx commands for 
seizing control of and debugging currently active processes. 

Appendix A, "dbx Command Summary," lists commands, aliases, syntax, 
and gives a brief description of the commands. 

Appendix B, "Sample Program," shows an example of a dbx program. 

Appendix C, "Questions and Problems," has solutions to some dbx 
questions and problems. 



1.2 Conventions 

This document uses the standard UNIX convention for referring to entries in 
the IRIX™ documentation. The entry name is followed by a section number 
in parentheses. For example, cc(l) refers to the cc manual entry in Section 1 
of the IRIX User's Reference Manual. 

In command syntax descriptions and examples, words in italics represent 
variable parameters, which you replace with the string or value appropriate 
for the application. Square brackets ([]) around an argument indicate that the 
argument is optional. 

In text descriptions, file names and IRIX commands are printed in italics. 
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1.3 Relevant Documentation 

You may find useful information to help you plan and set up your network 
in these documents: 

• Learning to Debug With edge, (edge is Silicon Graphics Inc.'s graphical _ 
interface to dbx) £ 

• IRIX User's Reference Manual, dbx(l) man page 
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2. Getting Started 



This chapter introduces dhx. It offers a general discussion of basic 
debugging commands, as well as some tips about how to approach a 
debugging session. The first section explains the basic commands and 
procedures for debugging a simple program. Experienced users might want 
to skip this chapter. 



2.1 Debugging a Simple Program 

It's easy to debug a simple program. For example, assume that you want to 
debug a simple program such as the one in Appendix B, anthrax.c. To use 
anthrax. c as an example, first change the call to printline from: 

Printline (filinel) ; 

to 

Printline (linel) ; 

Now the printline call is incorrect, so the program will write to a core file 
(called a "coredump") when you run it. 
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Here's how to debug this new, broken, version of anthrax.c: 

1. Compile the program: 

cc -g anthrax.c 

2. Run the program (it will coredump): f 
a. out anthrax.c 

3. Start dbx: 

dbx a. out core 

4. Look at the stack trace: 
t 

5. Now you know the problem is in printline. Look at the source where it 
coredumped: 

c 

6. Print the pointer: 

print pline 

The pline looks like a list of characters ~ something's obviously wrong. 

7. Move up the stack trace to look at the caller: 

up 



c 



2-2 dbx Reference Manual IRIS-4D Series 



8. Look at the source where it coredumped: 
w 

9. Print the contents of linel : 

print linel 

10. Stop at the start-up point: 

stop in printline 

1 1 . Run the program: 

run 

12. It stops in printline. What is the pointer? 

print pline 

It looks just like when it coredumped. Obviously, it needs a pointer. 

13. Now you can quit dhx: 

q 



Version 3.0 Getting Started 2-3 



2.2 Source-Level Debuggers 

dhx is a source-level debugger. Source-level debuggers let you trace 
problems in your program object at the source code level, rather than at the 
machine code level, dhx enables you to control a program's execution, 
symbolically monitoring program control flow, variables, and memory 
locations. You can also use dhx to trace the logic and flow of control to 
acquaint yourself with a program written by someone else. 



2.3 Activation Levels 

Activation levels define the currently active scopes (usually procedures) on 
the stack. The activation stack is a list of procedure calls. The most recently 
called procedure or block is numbered 0. The next procedure called is 
numbered 1. The last activation level is always the main program. 

Activation levels can also consist of blocks that define local variables withip 
procedures. You see activation levels when you do stack traces (see the 
where command) and when you move around the activation stack (see the 
up, down, mdfunc commands). 



2.4 Locating the Failure Point 

Even if your program compiles successfully, it still might crash when you 
try to run it. When a program crashes, it generates a terminating signal that 
instructs the system to write out to a core file. The core file is the memory 
image of the running program. 

The first step in figuring out why a program fails is to look at the 
terminating signal. In particular, it's often useful to know which line 
generates the signal. 
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To determine which line generates the terminating signal, follow these 
steps: 

1. Copy the core file to the directory containing the failed program. 

2. Invoke dbx for the failed program, dhx automatically reads in the local 
core file. 

3. Do a stack trace using the where command to locate the failure point. 

For example, suppose you're debugging a program called madmax. If the 
program fails on line 83, the where command returns this message: 

main(argc = 4, argv = 0x7fffc794) ["madmax. c" : 83 , 0x400228] 



Note: If you don't strip symbol table information from your program 

object, you can do a stack trace on a program that wasn't compiled 
using the debug flag, -g. 



2.5 Debugging Your Programs 

Whether you are debugging a crashed or a normally terminating program, 
you need to know the value of program variables at various points 
throughout the code. To do this, you should set several breakpoints in your 
program. A breakpoint stops program execution and lets you examine the 
state of the program at that point. Chapter 9, "Setting Breakpoints," 
discusses this topic in more detail. 
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Set breakpoints throughout your program. Look at your program carefully to 
determine where there are likely to be problems, and be sure to set 
breakpoints in these problem areas. If the program crashes, first determine 
which line caused it to crash, then set a breakpoint just before that line. 

There are many dbx commands you can use to trace a variable's value. This 

is the simplest method for tracing a program variable: | 

1 . Use stop to set breakpoints in the program at locations where you want 
to print the value of a variable. See Chapter 9 for more details. 

2. Use run or rerun to run the program under dbx. The program pauses at 
any breakpoint you set 

3. When the program pauses at a breakpoint, use print to print the value of 
the program variables you want to follow. 

4. Use cont to continue execution past a breakpoint. However, you cannot 
continue execution past a line that crashes the program. 

Chapter 4, "Commands and Expressions," explains these commands in more 
detail. Appendix A, "dbx Command Summary," lists all the dbx commands. 



2.6 Studying a New Program 

dbx is a useful tool for examining the flow of control in a program. When 
studying the flow of control within a program, use the dbx commands stop, 
runl rerun, print, next, step, and cont. This is the procedure: 

1. Use stop to set breakpoints in the program. When you execute the 
program under dbx, it stops execution at the set breakpoints. 

If you want to review every line in the program, set a breakpoint on the 
first executable line. If you don't want to look at each line, set 
breakpoints just before the sections you intend to review. 

2. Use run and rerun to run the program under dbx. The program stops at 
each breakpoint 

3. Use print to print the value of a program variable at a breakpoint. 
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4. Use next , step, or cont to get past a breakpoint and execute the rest of the 
program. 

• next executes the next line; if it is a procedure, next executes it but 
does not step down into it. 

• step executes the next line of the program. If the next line is a 
procedure, step steps down into the procedure. 

• cont resumes execution of the program past a breakpoint and does 
not stop until it reaches the next breakpoint or the end of the 
program. 

For more information about these commands, see Chapter 4, 
"Commands and Expressions," or Appendix A, "dbx Command 
Summary." 



2.7 Avoiding Common Pitfalls 

You may encounter some common problems when you debug a program. 
These problems and their solutions are listed below. 

• If the debugger won't display variables, recompile the program with the 
-g compiler flag. If your program is a FORTRAN program and you 
started dbx with -F, you must use the readsyms command to make 
variables in common visible. 

• If the debugger's listing seems confused, try separating the lines of 
source code into logical units. The debugger might get confused if 
there's more than one source statement on the same line. 

• If the debugger's executable version of the code doesn't match the 
source, recompile the source code. The code displayed in the debugger 
is identical to the executable version of the code. 

• If code appears to be missing, it may be contained in an include file or a 
macro. The debugger treats include files and macros as single lines. To 
debug code from an include file, remove the source from the include file 
and compile the source as part of your source program. To debug a 
macro, expand the macro in the source code. 
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3. Running dbx 



This chapter explains how to run dbx — specifically how to: 

• compile your program for debugging 

• create a .dbxinit command file (optional) 

• invoke dbx from the shell 

• use the corefile and givenfile commands 

• get on-line help 

• end your debugging session 



3.1 Compiling Your Program 

Before using dbx, compile the program using the -g option. The -g 
compile option inserts symbol table information into your program object so 
the local variables are visible to dbx. dbx uses the symbol table information 
to list local variables and to find source lines. 

If you use dbx to debug code that was not compiled using the -g flag, local 
variables are invisible to dbx, and source lines may appear to jump around 
oddly as a result of various optimizations. Since it's harder to debug code 
without reliable references to lines of source code, always recompile a 
program you want to debug using the -g flag, if possible. 
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3.2 Building a .dbxinit Command File 

You can use your system's editor to create a .dbxinit command file. This is 
a file in which you list various dbx commands, which are then automatically 
executed when you invoke dbx. You can put any dbx command in the 
.dbxinit file. If any of these commands require input, the system prompts f 
you for it. V 

When you invoke dbx, it looks for a .dbxinit file in the current directory. If 
the current directory does not contain a .dbxinit file, dbx looks for one in 
your home directory. (This assumes you set the IRIX system HOME 
environment variable.) 

Here's an example of a .dbxinit file: 

set $page = 5 
set $lines = 20 
set $prompt = "DBX>" 
alias du dump 

Note: The $page, $line$, and $prornpt are all dbx system variables. For 
complete description of these and other dbx system variables, see 
"Predefined dbx Variables" in Chapter 6. f 
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3.3 Invoking dhx 

To invoke dbx from the shell command line, type dbx. 
The syntax is: 

dhx loptions] [program [corefile] ] 

Examples 

dhx a. out 

dhx a. out /usr/tmp/cor« 

dhx -P myprog 

dhx -p 3409 

There are several optional parameters listed on the following page. After 
invocation, dbx sets the current function to the first procedure of the 
program. If you specify corefile, dbx lists the point of program failure. For 
core files, you can do stack traces and look at the code; however, you cannot 
force the program to execute past the line that caused it to crash. 

If you don't specify a corefile, dbx looks in the current directory for a file 
named core. If it finds core, and if core seems (based on data in the 
corefile) to be a coredump of the named programs, dbx acts as if you had 
typed "core" as the corefile. 

Use the environment variable DBXINIT (see the previous section) to hold 
dbx command line options. The debugger inserts the contents of DBXINIT 
before the command line options. This is most useful for options not 
recognized by edge(l), since it provides a way to pass options to dbx even if 
edge does not recognize them. Currently the options -e and -F are 
recognized by dbx but not by edge. 

Since program is given on the command line, the program file named there 
can be referred to as the givenfile. (See the givenfile and corefile commands 
for more information.) 

The following table lists specifications for dbx options. 
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Option 



Select this option to... 



-I dir 



-c file 



-a. 



-r program [arg] 



-p PID# 
-P name 

-e num 



Tell dbx to look in the 
specified directory for 
source files. To specify 
multiple directories, use a 
separate -I for each. If no 
directory is specified when 
you invoke dbx, it looks for 
source files in the current 
directory and in the object 
file's directory. From dbx, 
change the directories 
searched for source files 
with the use and dir 
commands. 

Select a command file other 
than dbxinit. 

Use interactive mode. This 
option does not treat #sas 
comments in a file. It also 
prompts for source even 
when it reads from a file 
and has extra formatting, as 
if for a terminal. 

Run the named program 
upon entering dbx, using 
the specified arguments. 
You cannot specify a core 
file with -r. 

Debug the process specified 
by the FID number. 

Debug the running process 
with the specified name 
(name as described in 
Ml))- 

Choose a larger size for the 
evaluation stack (as large as 
you want). The default 
stack size is 20,000 bytes. 
num = number of bytes. 
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Option Select this option to... 

-F Fastpath load the symbol 

table of the program to be 
debugged. This only helps 
programs using FORTRAN 
common ~ for large 
FORTRAN programs, 
start-up time can be long. 
This option keeps dbx from 
loading the internal fields 
of common, making dbx 
startup much faster. After 
startup, the variables in 
common are invisible to 
dbx. Use the readsyms 
command to read in 
common symbols when and 
where you need them 
visible. 

-k Turn on kernel debugging. 

When debugging a running 
system, specify Idevlkmem 
as the core file. 

-C Suppress the automatic 

truncation of C++ variable 
names. This option causes 
the full long names output 
by cfront to cc to be visible. 
This is useful when you 
think dbx has truncated a 
name improperly, but it 
makes C++ code more 
difficult to work with. 

Table 3-1. (continued) dbx Options 
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3.4 Using the corefile and givenfile Commands 

After you invoke dbx, you can debug a core file or another program from 
within the debugger by using the corefile or givenfile commands, 
respectively. You can use these commands without an argument or with a 
specified file. 



3.4.1 The corefile Command 

The command: 

corefile 

displays the name of the core file. If the corefile is currently used by dbx, 
this command displays program data. If you type: 

corefile file 

dbx uses the core f&t,file for program data. This command does the same 
thing as if you typed dbx file corefile. 

3.4.2 The givenfile Command 

The command: 

givenfile 

displays the name of the program being debugged. If you type: 

givenfile file 

dbx kills the current running processes and reads in file's symbol table. This 
command does the same thing as if you typed dbx file. 
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3.5 On-line Help 

The dbx command help shows the dbx help file, dbx displays the file using 
the command name given by the $pager environment variable. For ease of 
use, it is best to put the following command in your .dhxinit file: 

set $pagor = "vi" 

If you don't like vi, just substitute the name of your favorite editor. 

When the above entry is in your .dbximt file, dbx brings up the help file in 
your editor. You can then use the editor's search commands to look through 
the help file quickly. Quit the editor to get back to dbx. 

Under edge, the help file appears in a separate window, which you can 
leave on the screen for easy access. The format and colors of this window 
are controlled by the dbx debugger variable $helpwshformat. The wsh(l) 
options -Hand -c are automatically added by dbx. Seethews7i(l)for 
more information on its options. Use the window-menu "quit" entry on the 
help window to quit. 



3.6 Quitting dbx 

Use the quit command to end a debugging session, just type: 

quit 
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4. Commands and Expressions 



This chapter describes dbx commands and expressions and includes: 

• strings 

• expression and precedence 

• data types and constants 

• comments 

• registers 

• keywords 

• C type-casts 

• pointers and structures 

• C++ function and variable names 
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4.1 Strings 

In general, dbx recognizes the following escape sequences in quoted strings 
(per the standard C language usage): 

\fl \n \r \f \b \t V V 

dbx strips the escapes (\) and the surrounding quotes while creating the 
internal representation of the string. You can use the double-quote character 
(") to quote strings; dbx also recognizes the single-quote character ( f ). 



. mrx . mi (refers to the global) 

. mrx . mrx . ml (refers to the local) 



C 



4.2 Qualifying Variable Names 

dbx qualifies variables with the file, the procedure, a block, or a structure. 
You can manually specify the full scope of a variable by separating scopes 
with periods. For example, look at this expression: 

mrx . main . i 

Here, mrx is the current file, main is a procedure, and i is a variable. | 

A leading dot (a period at the beginning of the identifier) tells dbx that the 
identifier is a module (file). For example: 

. mrx . main . i 

Here, the period at the beginning of the line indicates that mrx is a file. In 
this example, main is a procedure and i is a variable. 

The leading dot is very useful when a file and a procedure have the same 
name. For instance, suppose mrx.c contains a function called mrx. Further, 
suppose that mrx contains a global variable called mi and a local variable, 
also called mi. Then, for example: 



c 
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4.3 Expressions and Precedence 

dbx recognizes expression operators from C and FORTRAN 77. Operators 
follow the C language precedence. The tables that follow show debugger 
operations, C language and FORTRAN operators, and data types. 



Syntax Description 



"file" #exp Uses specified line number exp in 
the specified file 9a /i/i, and returns 
the address of that line. 

proc #exp Uses the specified line number, 

exp, in the specified procedure, 
proc, and returns the address of that 
line. 

#exp Takes the specified line number, 

exp, and returns the address of that 
line. 

Table 4-1. Debugger Operations 

Note: The table above describes the interactive case. In a script, use two 
pound (##) signs (for example, ##exp). 



Type Operators 



Unary & + - * sizeof() - (type) (type*) 

Binary « » " !==!=<=>=<>& 

&& I II + - * % [] -> 



Table 4-2. C Language Operators 

Note: The sizeof operator specifies the number of bytes retrieved to get an 
element, not (number_of_bits+7)/8. 
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Type 

Unary 

Binary 



Operators 



// 



Table 4-3. FORTRAN Operators 



Note: Use // (instead of /) for divide. 

FORTRAN array subscripting must use square brackets, [ ] , instead of 
parentheses, (). 



4.4 Data Types and Constants 

dhx commands can use the built-in data types listed in the following table. 



Data Types 


Description 


$address 


pointer 


$unsigned 


unsigned pointer 


$char 


character 


$boolean 


boolean 


$real 


double precision real 


$integer 


signed integer 


$float 


single precision real 


$double 


double precision real 


$uchar 


unsigned character 


$short 


16-bit integer 



c 



Table 4-4. Data Types 

You can also use the built-in data types for type coercion. For example, use 
them to make a variable a type that isn't supported in the language you're 
using. 



( 
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Constant 


Description 


false 


zero 


true 


nonzero 


nil 


zero 


Oxnumber 


hexadecimal 


Otnumher 


decimal 


number 


decimal 


number, [number] [elE][+l-] [exp\ 


float 



Table 4-5. Input Constants 
When using data types and constants, remember: 

• Overflow on non-float uses the right-most digits. 

• Overflow on float uses the left-most of the mantissa and the highest or 
lowest exponent possible. 

• Setting the $octin dbx variable changes the default input type to octal. 

• Setting the $hexin variable changes the default input type to 
hexadecimal. If both variables are set, Shexin takes precedence over 
Soctin. See "Predefined dbx Variables" in Chapter 6. 

• Setting the $octints dbx variable changes the default output type to octal. 

• Setting the $hexints variable changes the default output type to 
hexadecimal. If both variables are set, $hexints takes precedence over 
$octints (see Chapter 6). 

A pound sign (#) introduces a comment in a dbx script file. When dbx sees 
a pound sign in a script file, it interprets all characters between the pound 
sign and the end of the current line as a comment. 

In interactive mode, the pound sign is not a comment character (you can't 
type a comment interactively). Instead, it identifies an expression as a line 
number. In interactive use, when dbx encounters a pound sign, it interprets 
the characters between the pound sign and the end of the current line as a 
line number, and it calculates the address of that line number. 
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To indicate a line number in a script, use two pound signs (##). For 
example, suppose you want to tell dbx to print the address of line 27 of the 
current file. In a script, type: 

print ##27 

In interactive session, type: g^ 

print #27 



4.5 Registers 

Table 4-6 contains a list of dbx hardware registers with brief descriptions. 
Table 4-7 shows alternate names (aliases) for some of the registers. These 
are useful for debugging machine code. 

The $regstyle variable controls which name is shown by dbx (for those 
registers that have alternate names). 



( 



c 
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Alias 


Description 


$pc 


current user pc 


$sp 


current value of stack 




pointer 


$rn 


register n 


$mmhi 


most significant 




multiply/divide result 




register 


$mmlo 


least significant 




multiply/divide result 




register 


$fcsr 


floating point control and 




status register 


$feir 


floating point exception 




instruction register 


$cause 


exception cause register 


$dO, $d2..$d30 


double precision floating 




point registers 


$f0,$f2..$f30 


single precision floating 




point registers 



Table 4-6. Hardware Registers 
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Alias 


Alternate 


Description 


$rO 


$zero 


always 


$rl 


$at 


reserved for assembler 


$r2..$r3 


$v0..vl 


expression evaluations, 
function return values, 
static links 


$r4..$r7 


$aO..$a3 


arguments 


$r8..$rl5 


$t0..t7 


temporaries 


$rl6-$r23 


$s0..$s7 


saved across procedure 
calls 


$r24..$r25 


$t8..$t9 


temporaries 


$r26..$r27 


$kO..$kl 


reserved for kernel 


$r28 


$gP 


global pointer 


$r29 


$sp 


stack pointer 


$r30 


$s8 


saved across procedure 
calls 


$r31 


$ra 


return address 



._„„_ 



4.6 Keywords 

A list of dhx keywords appears below. When naming variables in your 
program, it's best not to use these keywords. If one of the variables is 
identical to a dhx keyword, there will be some minor problems. 



all 


not 


and 


or 


at 


output 


div 


pgrp 


if 


pid 


in 


sizeof 


input 


to 


mod 


xor 



c 
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Here are some additional keywords that are used as C casts: 



signed 


struct 


unsigned 


union 


short 


enum 


long 


double 


int 


float 


char 





You can turn off these C cast keywords by typing: 

set $ctypenames=0 

This prevents these keywords from getting in the way of non-C programs. 
For more information about C casts, see the following section, "C Type- 
Casts." 

To print a variable name that is also a dbx keyword, put the variable in 
parentheses when you type it. For example, suppose you have a variable 
called and, and you type this: 

print and 

You will get a syntax error message. Instead, you should type: 

print (and) 

which tells dhx to print the value of the variable and. 



4.7 C Type-Casts 

Most C casts now work properly. The exceptions are casting values to or 
from float or double. 

To turn off the C cast keywords see the previous section, "Keywords." 
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4.8 Pointers and Structures 

You can use ->, " , and . almost interchangeably for structure data 
references and pointer dereferences. In the future, this may be changed to 
reflect language usage precisely, so that x~ . b and x . b are different 
(similarly for C). It is therefore a good idea to write scripts with pointers 
and structure references as much like your language as dbx allows. That 
way, future changes won't break your scripts. 



4.9 Case Sensitivity in Variable Names 

When dbx searches its tables for variable names, it matches the name you 
type against names in its tables according to the $casesense variable. 

If $casesense is 0, case is ignored. If $casesen$e is 1, case is always 
checked. 

If $casesense is 2, (the default), then the language in which the variable was 
defined is taken into account (e.g., C and C++ are case sensitive while 
Pascal and FORTRAN are not). 

For example, to make dbx always distinguish between upper and lower case 
(e.g., A is not the same as a): 

set. $Gasasense=l 



4.10 C++ (2.0) Function Names 

To make debugging of C++ 2.0 programs easy, use the following special 
syntax for C++ names. This syntax does not work with C++ 1.2. 

Refer to C++ functions with their source name. For example, with class A: 

A: :func 



c 



c 
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For globals: 

: :£unc 

For special functions: 

A: :new 

A : : delete 

A:: class (constructor) 

A: : -class (destructor) 

A : : + (example of overloaded operator) 
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( 



c 



( 



5. The dbx Monitor 

This chapter explains: 

• the history feature and the history editor 

• how to use dbx command line editing 

• how to type multiple commands 
Examples: 

history 
hed 1,9 
!-3 
! ! 
hed all 
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Syntax 


Select this command to: 


history 


Print the items in the 
history list. 


! [string] 


Repeat the most recent 
command that starts with 
the specified string. 


! [integer] 


Repeat the command 
associated with the 
specified integer. 


! [-integer] 


Repeat the command that 
occurred integer times 
before the most recent 
command. 


i i 


Repeat the last command. 


[command]; [command] 


Type multiple commands 
on the same line. 


hed 


Edit only the last line of 
history. 


hed numl,num2 


Edit the range of line 
numbers from numl to 
num2. 


hed all 


Edit the entire current 
history. 


set $repeatmode=l 


Set dbx so that a carriage 
return on an empty line 
works like a double 
exclamation point ( ! ! ). 



c 



c 



Table 5-1. History Commands 



c 
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5.1 History Commands {history and /) 

The dbx history feature is similar to the C shell's history feature. However, 
dbx history works only at the beginning of the line. Don't use history in the 
middle of the line or with !$. 

Set the number of lines of history by using the $lines variable. The default is 
20. To reset this variable, use the set command (see "Setting dbx Variables 
(set)" in Chapter 6). For example: 

set $lines=200 



To see a list of the commands in your history list, type: 

history 

To repeat a previous command, use one of the exclamation point (/) 
commands. For example: 

!pr 

executes the last command that began with the letters pr. 



5.2 The History Editor {bed) 

The history editor, hed is available with dbx (not with edge). The hed editor 
lets you use your favorite editor on any or all of the commands in the 
current dbx history. 

When you use the hed command, dbx puts you in a temporary file, which 
you can edit. When you quit the editor, any commands left in this 
temporary file are automatically executed. 

hed uses the editor named in the $editor variable. The command: 

set $pimode=l 

causes the commands to be displayed as they are executed. 
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Here are some examples. To edit the last line of history, type: 

hod 

To edit lines 3 through 9, type: 

bed 3, 9 

To edit the entire current history, type: 

hed all 



5.3 Multiple Commands 

Use the semicolon (;) as a separator to type multiple commands on the same 
command line. This can be useful when you use the when command. See 
"Writing Conditional Code" in Chapter 9. 

Example: 

when at "myfile.c" :37 {print a ; where ; print b} 



( 



C 
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6. Controlling dhx 



This chapter describes dbx predefined variables and aliases and also explains 
how to control dbx by: 

• creating and changing dbx variables 

• creating and removing command aliases 

• recording and playing back input and output 

• invoking a shell from dbx 

• checking and deleting dbx status items 
Examples: 

set $repeatmode=l 

set $lines=200 

alias fv "printf \"%20.3f , \\n\" " 

status 

delete 3 

sh cat small. C 

set $rimode=l 

record 

record output my__ journal 

unrecord all 
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Syntax 



Select this command to. 



alias 
alias name 



alias name "string 



alias namename2 

alias name(argl ,...argN) "string" 



delete iteml...itemN 
delete all 
playback input \file] 



playback output [file] 



record 



List all existing aliases. 

List the alias string for 
name. The alias value is 
inserted in quotes with 
escape characters to show 
how the alias "string" was 
typed. See the help file 
(lusrllibldbx.help) 
EXPRESSIONS section for 
additional information. 

Define a new alias. See the 
help file {lusrllibldbx.help) 
EXPRESSIONS section for 
additional information. 

Define a new alias. 

Define a new alias. When 
using the alias, the actual 
arguments are substituted 
for "string". 

Deletes the specified items. 

Delete all the status items. 

Execute the commands 
from the specified file, file. 
The default file is the 
current temporary file 
created for the record input 
command. 

Print the commands from 
the specified file,/i/e. The 
default file is the current 
temporary file created for 
the record output 
command. 

Show a list of the current 
recording sessions. Each is 
assigned a number. 



c 



c 



Table 6-1. Commands to Control dbx 
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Syntax 



Select this command to... 



record input [file] 



record output [file] 



set 

set var = exp 

sh [com] 

status 

source [file] 

unalias alias 
unrecord [N] 

unrecord all 

unset var 



Record everything you type 
to dbx in the specified file, 
file. The default file is a 
temporary dbx* file in the 
limp directory. 

Record all dbx output in the 
specified file,yi/e. The 
default file is a temporary 
dbx file in the I imp 
directory. 

Display a list of predefined 
and user defined variables. 

Define (or redefines) the 
specified variable, var. 

Call a shell. Execute the 
specified shell command, 
com. 

Check the status of 
commands. 

Execute dbx command 
ixomfile. 

Remove the specified alias. 

Turn off recording session 
N and close the file 
involved. 

Turn off all recording 
sessions and close all files 
involved. 

Unset the value of the 
specified variable, var (it 
disappears from the list). 



Table 6-1. (continued) Commands to Control dbx 
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6.1 Predefined dbx Variables 

Predefined dbx variables are listed in the table that follows. The predefined 
variable names begin with "$" so they don't conflict with variable, 
command, or alias names. 



c 



c 
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Variable 



Default 



Select this variable to... 



$addrfmt 



$casesense 



$charisunsigned 1 



Sctypenames 



$ cure vent 
$curline 
$curpc 
$cursrcline 



'Ox%x' ' C format for address 
printing ($pc, $pc of 
source line, $pc offset of 
instruction in 
procedure). 

L If 1(0), case 

(in)sensitive;if2, 
depends on the 
language. 

If 1, a (char) cast is 
taken as unsigned;if 0, a 
(char) cast is taken as 
signed. 

If 1, words unsigned, 
short, long, int, char, 
struct, union, enum are 
keywords usable only in 
type-casts. If 0, struct, 
union, enum are 
ordinary words with no 
predefined meaning (in 
C modules, the others 
are still known as C 
types). 

Current event id for 
trace/ stop/when. 

The current line number 
for execution. 

Current program 
counter. 

Current source listing 
line. 



Table 6-2. Predefined Variables 
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Variable 



Default Select this variable to., 



$datacache 



$defaultin 



$defaultout 



$editor 



$funcentrybylines 



If 0, then cache multiple 
data accesses while 
stopped. Setting to is a 
good idea. No visible 
loss in performance. 

Default record input file 
name if none specified 
in playback input or 
record input. 

Default record output 
file name if none 
specified in playback 
output or record output. 

The name of the editor 
to invoke (with edit 
command). Default is 
EDITOR environment 
variable. If EDITOR 
missing, defaults to vu 

Only applies to Pascal, 
C,andC++.IfO,dfcc 
uses disassembly of the 
code to estimate the 
location of the first line 
of each function. If 1, 
dbx uses the line 
numbers in the line 
table; this does not work 
well if the first line of 
code is on the same line 
as the function opening 
brace " { " as it often is in 
short C++ functions. 



Table 6-2. (continued) Predefined Variables 
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Variable 


Default 


Select this variable to... 


Sgroupforktoo 





If 0, only sproc'd procs 
are added to grouplist 
automatically. If 1, then 
fork'd & sproc'd procs 
added to grouplist. 


$hexchars 





If 1, output chars in hex, 
using C format "%x". 


$hexin 





If 1, input constants are 
assumed in hex. This 
overrides $octin. 


$hexints 





If 1, output integers in 
hex and override 
$octints. 



$hexst rings 



If 1, output strings and 
arrays in hex. For char 
arrays, if 1, the null byte 
is not taken as a 
terminator. Instead, the 
whole array (or $maxlen 
values, whichever is 
less) is printed. If 0, then 
a null byte in an array is 
taken as the end of the 
array (the length of the 
array and $maxstrlen 
can terminate the array 
print before a null byte 
is found). 



Table 6-2. (continued) Predefined Variables 
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Variable 



Default Select this variable to.. 



$hide_anonymous 1 
blocks 



$lastchild 



$lines 



$listwindow 



20 



Anonymous inner 
blocks ({ } in C) are not 
shown in stack traces or 
counted in up/down 
commands. If 0, these 
blocks are shown, 
counted. Set to if you 
have a local variable in 
an inner block hiding a 
variable with the same 
name in an outer block 
and want to see the 
value of the outer 
variable. If 0, the up 
command will take you 
to the outer scope where 
a print command will 
show the variable visible 
in that local scope. 

The process id of the 
last child 
forked! sproced. 

Number of lines in 
history list. 

List command size. 



Table 6-2. (continued) Predefined Variables 
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Variable 



Default Select this variable to... 



$main 



main 



$maxstrlen 



128 



$mp__program 



$naptime 



At startup, dhx sets 
source file and line to 
the function named in 
this string variable. It 
can be any procedure. It 
is only usefully set by 
dbx when it reads the 
process' symbol table, 
since it is used only 
once by dbx, before any 
commands are read. 

Maximum length printed 
for zero-terminated char 
strings and arrays. Char 
arrays are printed for 
array-length, $maxstrlen 
bytes, or up to a null 
byte, whichever comes 
first (see $hexstrings). 

If 0, sproc is treated like 
fork. If 1, sproc is 
treated specially. The 
children are allowed to 
run (they will block on 
multi-processor 
synchronization code 
emitted by mp 
FORTRAN). Set to 1 
only if mp FORTRAN 
code. Set to 1, mp 
FORTRAN code is 
easier to work with. 

Trace (no operands) and 
step n 9 next n will delay 
$naptime lOOths of a 
second after every 
instruction. See 
sginap(2). 
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Variable Default Select this variable to... 

$nextbreak 2 If 0, $stepintoall 

controls whether next 
will behave as if 
$nextbreak were 1 or 2. 
If 1, next will single- 
step through calls and 
will get back to the next 
statement. (Currently, 
stop if, trace, or when 
commands testing 
variables may fail with 
"not active," stopping 
execution.) This is slow 
but guarantees arrival 
back to the right place 
even if part of the code 
is compiled without 
symbols and is 
recursive. Also causes 
tracing of function 
values to be done in 
lower level functions 
(slow), but handy if a 
lower-level function 
uses a wild pointer or if 
data is passed by 
reference or is visible in 
upper levels, as in 
Pascal. If 2, a next will 
quickly execute calls 
with tracing and 
breakpointing. If the 
function calls itself, the 
next may stop at a later 
return from the function, 
not precisely the point 
of call (the stack trace 
will be deeper than 
expected). 

Table 6-2. (continued) Predefined Variables 
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( 



c 



Variable 



Default Select this variable to... 



$octin 

$octints 

Spage 
$pager 

$pagewindow 



$pagewidth 



$pid 

SpidO 

$pimode 



If 1 , input constants are 
assumed in octal ($hexin 
overrides $octiri). 

If 1, output integers in 
octal ($hexints=l takes 
precedence). 

1 If 0, then page screen 
output. 

The name of the 
program used to display 
help information. 

The size (length in lines) 
of page for paging. This 
controls when the "n?" 
or "More" prompt is 
displayed. 

Width of window in 
characters (assumes 
fixed-width font). Used 
by dbx to calculate how 
many screen lines are 
output, dbx never inserts 
newlines; the window 
software wraps the lines. 

Set current process for 
kernel debugging (-k). 

The process id of the 
given process. 

If 0, playback input 

prints commands as they 
are played back. 



Table 6-2. (continued) Predefined Variables 



Version 3.0 



Controlling dhx 6-11 



Variable 



Default Select this variable to... 



$printdata 



$print__exception_frame 



$printwhilestep 



$printwide 
$prompt 



If 0, print register 

contents when 
disassembling. 

Only available to dbx -k 
(not available unless you 
are doing kernel 
debugging). If 0, no 
special output is done. 
If 0, when doing where, 
up, or down, exception 
frames and struct 
sigcontext blocks are 
output in hex when the 
stack frame encounters 
one of these on the 
stack. This may be of 
some use. 

If 0, acts as if step[i] n 

was step[i] n times. 
With edge, green line 
steps through as 
program executes. If 0, 
step n steps n then 
displays (notifies edge). 

If 0, print compactly 

(wide). If 0, print arrays 
one element per line. 

(dbx) Prompt string. 



c 



Table 6-2. (continued) Predefined Variables 
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Variable 



Default Select this variable to.. 



$proxnptonfork 



$regstyle 



1 



Srepeatmode 
$showbreakaddrs 



If 1, prompt user to add 
child process to pool on 
fork. The reply is taken 
from the current input 
file (which may be the 
screen). If 0, child not 
added to pool. If 0, the 
running process does not 
stop on a fork or sproc. 
If 2, child added to pool. 
An exec always stops 
the running process. 

If 0, use hardware 
names for registers 
when disassembling. 

If 1, null line repeats last 
command. 

If 1, show the address of 
each breakpoint placed 
in the code each time it 
is placed. Removal of 
the breakpoints is not 
shown. If multiple 
breakpoints are placed 
at one location, only one 
of the placements is 
shown. Since 
breakpoints are 
frequendy placed and 
removed by dbx, the 
volume of output can be 
annoying when tracing. 



Table 6-2. (continued) Predefined Variables 
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Variable 



Default Select this variable to.. 



$stepintoall 



$tagfile 



"tags" 



$v±s±blemangled 



If 0, stepli] will step 
into all procedures 
compiled -g or -g2 or 
-g3 for which line 
numbers are available in 
the symbol table. This 
does not include 
standard library routines 
since they are not 
compiled -g[23]. If 1, 
stepli] will step into 
those plus procedures 
for which dbx can find a 
source file. If 2, stepli] 
will step into all 
procedures. 

String with name of file 
searched for tags. 
Defaults to tags. See 
ctags(l). 

Applicable to C++ 2.0 
only. If not 0, mangled 
names of functions print 
along with demangled 
form. 



Table 6-2. (continued) Predefined Variables 
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6.2 Setting dbx Variables (sef) 

The set command defines a dbx variable, sets an existing dbx variable to a 
different type, or displays a list of existing dbx defined variables. You 
cannot define a debugger variable that has the same name as a program 
variable. You can see the setting for a single variable by using the print 
command. (Recall that predefined variable names begin with "$" so they 
don't conflict with variable, command, or alias names.) 

For example: 

set 

set $promptonfork = 2 

set $prompt = " : : >" 

set set $myvar = (int) $myvar+l 

The dbx predefined variables are listed in the table at the beginning of this 
chapter. 



6.3 Removing Variables (unsef) 

Use the unset command to remove the specified dbx variable from the list. 
To see a full list of dbx variables, use the set command, or see the beginning 
of this chapter. 

For example: 

unset $myvar 



6.4 Creating Command Aliases {alias) 

Use the alias command to see a list of all current aliases or to define a new 
alias. 

dbx lets you create an alias for any debugger command. Enclose multi-word 
command names within double or single quotation marks. 
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dhx has a group of predefined aliases that you can modify or delete. In 
addition, you can add your own aliases. To do so, use the following syntax: 

alias name(argl,...argN) "string" 

When using the alias, the actual arguments are substituted in "string." For 
example: 

alias m(a,h) "print alf.a.b" 

m (my struct , i) 

#th© command is: print alf . my struct . i 

You can include aliases in the .dbxinit file if you want to use them in future 
debugging sections. 

For a complete list of predefined aliases, see the section titled "Predefined 
Aliases" that follows, or type to dbx: 

alias 

Also see the section "Alias Examples." 



6.5 Removing Command Aliases (unalias) 

The unalias command removes the specified alias from the current debugger 
session. All predefined aliases are restored the next time you start a 
debugging session. For example: 

unalias pd 



C 



( 
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6.6 Predefined Aliases 

To list current aliases, use the alias command. You can override any 
predefined alias by redefining it with the alias command or by removing it 
from the list with the unalias command. The following table shows the 
debugger predefined aliases. For example: 

alias 
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Alias 


Command 


Select this alias to... 


a 


assign 


Assign the specified 
expression to the 
specified program 
variable. 


b 


stop at 


Set a breakpoint at 
the specified line. 


bp 


stop in 


Stop in the specified 
procedure. 


c 


cont 


Continue program 
execution after a 
breakpoint 


d 


delete 


Delete the specified 
item from the status 
list. 


e 


file 


Display the name of 
the currently selected 
sourcefile. If you 
specify a file, this 
command makes the 
specified file the 
currently selected 
source file. 


f 


func 


Move to the 
specified procedure 
(activation level) on 
the stack. If no 
procedure or 
expression is 
specified, dbx prints 
the current activation 
level. 


g 


goto 


Go to the specified 
source line. 


h 


history 


List all the items 
currently in the 
history list. 



( 



( 



Table 6-3. Predefined Aliases 



( 
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Alias Command 



Select this alias to... 



status 



$curp/10i; set $curp=$curpf40 



next 



m 



nexti 



pd 



Pi 



print 



printf M %d\n M , 



playback input 



List all the currently 
set stop and trace 
commands. 

List the next 40 
bytes of machine 
instructions 
(approximately 10 
instructions). 

Execute the next n 
lines of source code. 
The default value is 
one line. This 
command does not 
step down into 
procedures. 

Execute the next n 
lines of machine 
code. The default 
value is one line. 
This command does 
not step down into 
procedures. 

Print the value of the 
specified variable or 
expression. 

Print the value of the 
specified variable in 
decimal. 

Replay dbx 
commands saved in 
the specified file. If 
no file is specified, 
dbx uses the 
temporary file 
specified by $default. 



Table 6-3. (continued) Predefined Aliases 
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Alias 


Command 


Select this alias to... 


po 


printf"0%o\n", 


Print the value of the 
specified variable or 
expression in octal. 


F 


printregs 


Print values 
contained in all 
registers. 


px 


printf ,, Ox%x\n", 


Print the value of the 
specified variable or 
expression in 
hexadecimal. 


q 


quit 


Exit dbx. 


r 


rerun 


Run the program 
again using the 
values specified in 
the last used run 
command. 


ri 


record input 


Record to the 
specified file all the 
commands you give 
to dbx. If you do not 
specify a file, dbx 
creates a temporary 
file. The name of the 
file is specified by 
$default. 


ro 


record output 


Record all the 
debugger output to 
the specified file. If 
no file is specified, 
output is recorded to 
a temporary file. 
The name of the file 
is specified by 
Sdefault. 



c 



Table 6-3. (continued) Predefined Aliases 
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Alias Command Select this alias to... 

s step Execute the next n 

number of lines. If a 
line contains a 
procedure, this 
command steps 
down into that 
procedure. The 
default is one line. 

S next Execute the next n 

number of lines. If a 
line contains a 
procedure, this 
command does not 
step down into that 
procedure. The 
default is one line. 

si stepi Execute the next n 

lines of assembly 
code. The default is 
one line. If aline 
contains a procedure 
call, this command 
steps down into the 
procedure. 

Si nexti Execute the next n 

lines of assembly 
code. The default is 
one line. If a line 
contains a procedure 
call, this command 
does not step down 
into the procedure. 

Table 6-3. (continued) Predefined Aliases 
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Alias 



Command 



Select this alias to... 



source playback input 



w 



where 



list$curline-4:10 



W 



list $curline-9:20 



wi 



$curpc-20/10i 



Replay dhx 
commands saved in 
the specified file. If 
no file is specified, 
dhx uses the 
temporary file 
specified by $default. 

Do a stack trace to 
show the current 
activation levels. 

List a window of 
code around the 
current line. This 
command shows the 
four lines before the 
current code line, the 
current code line, 
and five lines after 
the current code line. 
This command does 
not change the 
current code line. 

List a window of 
code around the 
current line. This 
command shows the 
nine lines before the 
current code line, the 
current code line, 
and 10 lines after the 
current code line. 
This command does 
not change the 
current code line. 

List a window of 
assembly code 
around the program 
counter. 



Table 6-3. (continued) Predefined Aliases 
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6.7 Alias Examples 

The following examples show various ways that you can use the alias 
command with the debugger. You must use escapes when using aliases with 
internal quotes. 

# printing a float/double with your own choice of size 
alias mypflt(v) "printf \"%6. 18f \\n\",v M 

mypf It (44 .551234567) # example using the alias 

alias pf2 "printf \"%27 . 3f \\n\", " 
pf2 32.3 

Some quoted strings (" ") in the following examples are split into two lines 
so they can be printed here. However, when you type strings (or any 
command), the entire string/command must appear on one line for dhx to 
recognize it. 

An easy way to follow linked lists is to use aliases and casts. The following 
example shows a linked list with next pointers and a pointer to the contents 
of the linked list: 

struct list { struct list *next; int *elt ; } *mylist; 

set $pimode=l 

# set up aliases for following the list: 
alias foil (p) "px ((struct list *) p) ->next ; 

px ((struct list *)p)->elt" 
alias show(t,p) "print * (t *) (p) " 

# then, an initial list element is pointed to by mylist: 

# use the following to print the first element and its 

# contents where I assume one knows the contents somehow 
foil (mylist) 

# use the "elt" address printed (assume it is 0x123) 

# and assume the element is a pointer to "struct something": 
show (struct something, 0x123) 

# using the "next" address printed (assume it was 0x345) 
foil (0x345) 

# which shows the next list structure. 

# And so on. 
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The following example has a similar scheme. The alias remembers the last 
pointer. 

# Assume we know the address of an element of 

# the list is at 0x1234 
set $p - 0x1234 

# Aliases, including "folly" below, must be defined on 

# one line; what looks like two lines is just one line 

# wrapped around. The cast to int in the "set $p « " is 

# essential! If left off,dbx will leave the $p reference 

# symbolic and dbx will get into an infinite 

# loop (use *C or your interrupt key) to get out of trouble 

# if you get into the infinite loop) . 

# Of course $p is an arbitrary choice-use any name desired. 

# The name is not required to start with $, though starting 

# with $ is a good idea as the name won't conflict 

# with program variable names. 

alias folly "print * (struct list *)$p ; set $p = 

(int) ((struct list *) ($p))->next" 
# 

# then each time you type "folly, " you see the next 

# element printed 
folly 

folly 

set $repeatmode=l 

# now after the initial "folly," simply pressing return 

# will print the next list entry 
folly 



C 



6.8 Showing Record State (record) 

Use record to show record input or record output session currently active. 
For example: 

record 



C 
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6.9 Recording Input (record input) 

Use the record input command to start an input recording session. Once 
you start an input recording session, all commands to dbx are copied to the 
specified file. You can start and run as many simultaneous dbx input 
recording sessions as you need. 

After you end the input recording session, use the command file with the 
source ox playback input commands to execute again all the commands 
saved to the file. See "Playing Back Input" later in this chapter. The syntax 
of record input is shown below, dbx saves the recorded input in the 
specified file. 
For example, to save the recorded input in a file called keving, type: 

record input keving 

If you do not specify a file to record input, dbx creates a temporary dbx file 
in the Itmp directory. The name of the temporary file is in the system 
variable $defaultin. You can display the temporary file name using the print 
command as follows: 

print $de£aultin 

Because the Itmpldbx* temporary files are deleted at the end of the dbx 
session, use the temporary file to repeat previously executed dbx commands 
in the current debugging session only. If you need a command file for use in 
subsequent dbx sessions, you must specify the file name when you invoke 
record input. If the specified file already exists, the new input is appended 
to the file. 



6.10 Ending a Record Session (unrecord) 

To end a dbx recording session, use the unrecord all or the unrecord 
[session #] command. Thus, to stop recording session 3, you would enter 
the dbx command: 

unrecord 3 
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To stop all recording sessions, use: 

unrecord all 

Note: The dbx status command does not report on recording sessions. To 
see whether there are any active recording sessions, use the record 
command. For example: 

record 



6.1 1 Recording Output (record output) 

Use the record output command to start output recording sessions within 
dhx. During an output recording session, dbx copies its screen output to a 
file. If the specified file already exists, dbx appends to the existing file. By 
default, the commands you enter are not copied to the output file. However, 
if you set $rimode to a non-zero value, dbx will also copy the commands 
you enter. 

Examples: 

set $r±mode=l 

record output my_output 

The record output command is very useful when the screen output is too 
large for a single screen (e.g., printing a very large structure). Within dbx, 
you can use the playback output command to look at the recorded 
information. After quitting dbx, you can review the output file using any 
IRIX system text viewing command (such as vi). 

For example, to record the dbx output in a file called gaff a type: 

record output gaffa 

To record both the commands and the output, type: 

set $r±mode=l 
record output gaf fa 



C 



C 
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If you omit the file name, dbx saves the recorded output in a temporary file 
in Itmp. The temporary file is deleted at the end of the dbx session. To save 
output for after the dbx session, you must specify the file name when giving 
the record output command. The name of the temporary file is in the 
system variable $defaultout. To display the temporary file name, type: 

print $d«faultin 

To end a record output session, use the unrecord all or specify a session 
number. For example, to end recording session 3, you would type: 

unrecord 3 



Note: The dbx status command does not report on recording sessions. To 
see whether there are any active recording sessions, use the record 
command without arguments. 



6.12 Playing Back Input (source or playback 
input) 

Use these commands to replay the commands that you recorded with the 
record input command. If you don't specify a file name, dbx uses the 
current temporary file that it created for the record input command. If you 
set the dbx variable $pimode to non-zero, the commands are printed out as 
they are played back. By default, $pimode is set to zero. 

Examples: 

playback input script_file 
pi script 2 
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6.13 Playing Back Output (playback output) 

The playback output command displays output saved with the record output 
command. This command works the same as the IRIX system cat command. 
If you don't specify a file name, dbx uses the current temporary file created 
for the record output command. 

Example: 

playback output ascript 



6.14 Invoking a Shell (sh) 

To invoke a sub-shell, type sh at the dbx prompt, or type sh and a shell 
command at the dbx prompt. If you invoke a sub-shell, type exit or press 
<ctri-d> to return to dbx. For example: 

sh tail mydata 
sh 



6.15 Checking the Status {status) 

Use the status command to check which, if any, of these commands are 
currently set: 

• stop or stopi commands for breakpoints 

• trace or tracei commands for line-by-line variable tracing 

• when command 
For example: 

status 



C 



( 



( 
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6.16 Deleting Status Items (delete) 

Use the delete command to remove items (e.g., breakpoints, conditionals) 
from the status list. For example, to remove all items from the status list, 
type: 

delete all 

To remove item number 3 from the status list, type: 

delete 3 
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7. Examining Source Programs 

This chapter explains how to: 

• specify source directories 

• move to a procedure 

• change source files 

• list source code 

• search for strings in source code 

• call an editor from dbx 

• print symbol names 

• print type declarations for variables 
Examples: 

dir x/b 

func somafunc 

list 1,30 

/abed 

edit " special. g" 

what is x 

where is y 
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Syntax 



Select this command to.. 



lexp 
?exp 

dir 

dir dir 1... dir n 

edit {file] [function] 



file [file] 



£ unc [prod] [exp] 



list [exp] [proc] 
list exp '.integer 



use 

use dirL.AirN 



Search ahead in the current 
source file for the specified 
regular expression, exp. 

Search back in the current 
source file for the specified 
regular expression, exp. 

List current directory. 

Add dirl...dirn to the 
current list of directories. 

Call an editor to edit the 
specified source file or 
function. Default is the 
current file or function. 

Change the current source 
file to specified file^fe. 
The default is the current 
file. 

Move to the activation level 
specified by the procedure 
or expression. Default is 
the current activation 
level(s). 

List the specified line(s) for 
Slistwindow. Default is the 
current line. 

Lists the specified number 
of lines, integer, starting at 
the specified line, exp. 

List the current directories. 

Specifies different 
directories, dirl, dir2, 
etc. 



Table 7-1. Commands to Examine Source Programs 



c 



c 



c 
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Syntax Select this command to... 

whatis variable Print the type declaration 
for the specified variable or 
procedure in your program. 

whereis variable Print all versions of the 
specified variable. 

which variable Print the currently active 

version of the specified 
variable. 



Table 7-1. (continued) Commands to Examine Source Programs 



7.1 Specifying Source Directories (use and dii) 

Unless you specify the -I option at invocation, dbx looks for source files in 
the current directory or in the object file's directory. The use command lets 
you change the directory list and list the directories currently in use. The 
command recognizes absolute and relative pathnames (for example, ./); 
however, it doesn't recognize the C shell tilde (~ ) syntax (e.g., -johnlsrc) 
or environment variables (e.g., $HOME/src). 

For example: 

use dirl 

makes dirl the only directory. The example: 

dir dirl 

adds dirl to the list of directories. 

To print the current directory list, you can type either: 

use 

or 

dir 
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7.2 Moving to a Specified Procedure (tunc) 

The func command moves you up or down the activation stack. The 
function can be a procedure name or an activation level number. To find the 
name or activation number for a specific procedure, do a stack trace with the 
where command. You can also move through the activation stack by using 
the up and down commands. For a definition of activation levels, see 
Chapter 2, "Getting Started." 

The func command changes the current line, the current file, and the current 
procedure if the named function is currently on the activation stack. 

This changes the scope of the variables you can access. You can use the 
func command when a program isn't executing and the function is not on 
the activation stack (when you want only to examine source code). 

For example: 

func x 

changes the source view to function x. If function x is currently on the 
activation stack, the command (func x) also changes the scope of the 
variables you can access to those variables visible in x. 



7.3 Specifying Source Files {file) 

The file command changes the current source file to a file you specify. The 
new file becomes the current file, which you can search, list, and perform 
other operations on. For example: 

£ile whizzy.c 



C 



C 



c 
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7.4 Listing Your Source Code (list) 

The list command displays lines of source code. The dbx variable 
$listwindow defines the number of lines dbx lists by default. The list 
command uses the current file, procedure, and line unless otherwise 
specified. It moves the current line forward. 



7.5 Searching Through Source Code (/and 7) 

The / and ? commands search through the current file for regular 
expressions in source code. The slash (/) searches forward; the question 
mark (?) searches back from the current line. Both commands search the 
entire file. They wrap around to the beginning of the file and end at the 
point where you invoked the search command. 

To search forward in the code for a specified regular expression, type: 

/exp 

For example: 

/a.*xy 

To search backward in the code for a specified regular expression, type: 

?exp 
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7.6 Calling an Editor (edit) 

The edit command lets you make changes to your source code from within 
dbx. For example, to edit a file named soar.c from within dbx, type: 

adit, soar.c 

For the changes to become effective, you must recompile and rerun your 
program. The edit command loads the editor that you set as an environment 
variable editor. If you don't set the environment variable, dbx assumes the 
vi editor. When you exit the editor, it returns you to the dbx prompt. 



c 



7.7 Printing Symbolic Names (which and 
whereis) 

The which and whereis commands print program variables. These 
commands are useful for programs that have multiple variables with the 
same name occurring in different scopes. The commands follow the rules 
described in "Qualifying Variable Names" in Chapter 4. ^ 

Examples: ^ 

whereis a 
which b 



( 
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7.8 Printing Type Declarations {whatis) 

The whatis command lists the type declaration for variables and procedures 
in your program. For example, to list the type declaration for the variable, 
x 9 type: 

whatis x 

For a procedure called quahog, type: 

whatis quahog 

Since the same name sometimes applies to source files as well as variable 
names, the example: 

whatis carpet 

may display: 

source file "carpet. c" 
(int) carpet 
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c 
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8. Controlling Your Program 



This chapter explains how to control a program by: 

• running and rerunning the program 

• stepping through the program one line at a time 

• returning from a procedure call 

• starting at a specified line 

• continuing after a breakpoint 

• assigning values to program variables 
Examples: 

run 

run -f data2 < in data >outdata 

step 

return 

cont 

assign c = 27 
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Syntax 



Select this command to.. 



assign expl = exp2 
cont 

cont signal 

cont to line 

cont to proc 

cont signal to line 



cont signal to proc 



goto /me 
next [integer] 



Assign a new value to a 
program variable. 

Resume execution from the 
current line and wait for a 
break or other 
event. 

Send signal signal to the 
process, resume execution, 
and wait for a break or 
other event. 

Set a breakpoint at line, 
line, resume execution, and 
wait for a break or other 
event 

Set a breakpoint at the first 
line of procedure proc, 
resume execution, and wait 
for a break or other event. 

Set a breakpoint at line, 
line, send signal signal to 
the process, resume 
execution, and wait for a 
break or other event. 

Set a breakpoint at the first 
line of procedure proc, 
send signal signal to the 
process, resume execution, 
and wait for a break or 
other event. 

Start execution at the 
specified line, line, when 
execution is resumed. 

Step over the specified 
number of lines (default is 
1). This command does not 
step into procedures. 
Breakpoints in procedures 
stepped over are honored. 



( 



c 



Table 8-1. Commands to Control a Program 
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Syntax 



Select this command to.. 



rerun [argl...argN] [<\>\>&filel] 



return 



return iproc] 



run [argl...argN] [<\>\>&filel] 



step [integer] 



Rerun your program with 
the arguments you specified 
to the run command or with 
new arguments. The ofile 
arguments redirect program 
input and output. The 
>&file argument redirects 
stderr and stdout output to 
the specified file. 

Continue execution until 
control returns to the next 
procedure up on the 
activation stack. 

Continue execution until 
control returns to the 
named procedure. 

Run your program with the 
specified arguments. The 
ofile arguments allow you 
to redirect program input 
and output. The >&file 
argument redirects stderr 
and stdout output to the 
specified file. 

Execute the specified 
number of lines, integer, 
source code, integer refers 
to the number of lines to be 
executed in the current 
procedure, as well as any 
called procedures. Default 
is 1 source code line. 



Table 8-1. (continued) Commands to Control a Program 
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8.1 Running Your Program {run and rerun) 

The run and rerun commands start program execution. You can specify 
arguments to either command. Arguments to these commands override 
previous arguments. If you don't specify arguments to the run or rerun 
command, it uses the last set of arguments. 

Use these commands to redirect program input and output (works like 
redirection in the C shell). The optional <filei parameter redirects input 
to your program from the specified file. <file2 redirects output from the 
program to the specified file. The optional parameter >&file2 redirects 
stderr and stdout output to the specified file. 

Note: This output differs from the output you save with the record output 
command, which saves debugger (not program) output in a file. 
See "Recording Output (record output)" in Chapter 6. 

The arguments to the run command specify any program arguments that 
your program might have. For example, suppose you have a program called 
sik.c compiled as: 

cc -g sik.c -o sik 

Then, to run the program you would type: 

run sik 

To run the program with the specified arguments, use the following format: 
run largh..argN] [>fdel] [>fde2] 

Rerun the program, using the same arguments that were specified to the run 
command. If you specify new arguments, rerun uses those arguments: 

rerun [argl...argN] [<filel] [<file2] 



( 



C 



C 
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8.2 Executing Single Lines (step and next) 

The step and next commands execute a fixed number of source code lines as 
specified by exp. If you don't specify exp for step and next, dbx executes one 
source code line. If you specify exp, dbx executes the source code lines as 
follows: 

• For step and next, dbx does not take comment lines into consideration in 
interpreting exp. The program executes exp source code lines, regardless 
of the number of comment lines interspersed among them. 

• For step, dbx considers exp to apply to both the current procedure and to 
called procedures. The program stops after executing exp source lines in 
the current procedure and any called procedures. 

• For next, dbx considers exp to apply to only the current procedure. The 
program stops after executing exp source lines in the current procedure, 
regardless of the number of source lines executed in any called 
procedures. 



8.2.1 step [exp] 

This command steps only into procedures that have line numbers and were 
compiled with options -g, -g2,or -g3. The step command honors 
breakpoints in any procedures it steps over. 

The step command counts source lines in called procedures as well as the 
current procedure. The program stops after executing the specified number 
of source lines in the current procedure and any called procedures. 

You can force step to step into all procedures for which dbx can find a 
source file, even if the procedure was not compiled with symbols. To do 
this, type: 

set $stepintoall=2 

When you debug a source file compiled without symbols or compiled with 
optimization, the line numbers sometimes jump erratically, which may be 
quite confusing. 

If the file for a procedure has the same name as a file dbx can find, dbx will 
step into the procedure while reporting the source file it finds. The source 
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file found may not be the source file the procedure was compiled from; this 
will also be very confusing. 

You can also use $stepintoall to control step in other ways as shown below. 

• If =0 (the default), step[i] will step into all procedures compiled with 
-g, -g2, or -g3 for which line numbers are available in the symbol 
table. This does not include standard library routines since they are not 
compiled -g[23], 

• If =1, step[i] will step into the above plus procedures for which dhx can 
find a source file. 

• If =2, step[i] will step into all procedures. 

You can also use the variable printwhilestep to control step. 

• If =0, dbx acts as if the command: 

step[i] n 

was step[i] n times. With edge, green line steps through as the program 
executes. 

• lf=0, (the default): 

stepn 

steps n then displays (notifies edge): 

-trace (no operands) and step, next will delay 
$naptime lOOths of a second after every instruction. 

For more information, see sginap(2). 



c 



c 



c 
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8.2.2 next [integer] 

The next command steps over the specified number of lines (default is 1). 
This command does not step into procedures. Breakpoints in procedures 
stepped over are honored. See the previous description of SstepintoalU and 
the subsequent description of $nextbreak for information on modifying the 
behavior of next. 

$nexthreak does the following: 

• If =0, $stepintoall controls whether next will behave as if \$nextbreak 
were 1 or 2. If 0, step[i] will step into all procedures compiled -g, 
-g2, or -g3, for which line numbers are available in the symbol table. 
This does not include standard library routines since they are not 
compiled -g[23]. If 1, step[i] will step into those plus procedures for 
which dbx can find a source file. If 2, step[i] will step into all 
procedures. 

• If =1, a next command will single-step through calls and will get back to 
exactly the next statement. (In the current implementation, stop if or 
trace or when commands testing variables may fail with the message 
"not active," stopping the execution.) This is slow but guarantees arrival 
back at the right place even if part of your code is compiled without 
symbols and is recursive. It also causes tracing of function values to be 
done in lower-level functions, (which may be slow but handy) if a 
lower-level function uses a wild pointer or if data is passed by reference 
or is visible in upper levels, as in Pascal. 

• If =2 (the default), a next command will execute calls at full speed. If 
nexting from within a function that recurses, next may stop at a deeper 
level of recursion rather than at the next source. To avoid this, set 
$nextbreak=l. 



8.3 Starting at a Specified Line {goto) 

The goto command shifts program execution to a line you specify. This 
command is useful in a when statement, e.g., to skip a line that you know 
has problems. For example: 

goto 136 
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Note: The goto command cannot be used to go to a line outside the 
currently active procedure. 



8.4 Continuing after a Breakpoint (conf) 

The cont command resumes program execution after a breakpoint. These 
commands, cont to and cont in, go into effect when you issue them. When 
your program again reaches a breakpoint, you can reissue either cont to or 
cont in to continue, if desired. If signal is specified as a parameter, dbx 
sends the specified signal to the program and continues. 

Note: You can also use the dbx command, resume, to execute past a 
breakpoint. 

For example: 

cont. 
cont int 
cont sigint 



C 



C 



8.5 Variables and Registers 

The assign command changes the value of existing program variables or 
registers. For example: 

assign ac = 27 
assign y » 37.5 

If the "incompatible types" message appears when you try to assign a value 
to a pointer, use casts to make the assignment work. For example: 

# c definition might be struct x *y; 

# to set y to the null pointer; 
assign * (int *) (&y) = 



C 
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9. Setting Breakpoints 

Topics covered in this chapter include: 

• setting breakpoints at lines 

• setting breakpoints in procedures 

• running your program after a breakpoint 

• stopping for signals 

• stopping for system calls 
Examples: 

stop at 37 

stop at " compute . £ " : 2 9 

stop in my fun c 

cont 

cont sigfpe 

syscall catch call exit 

catch USR1 

ignore INT 
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Syntax 



Select this command to... 



catch 
catch [signal] 

ignore 
ignore [signal] 
stop [var] at line 



stop [var] at line if exp 



stop proc 



stop [var] in proc 



stop at 

stop [var] in proc if exp 



List all the signals that dbx 
catches. 

Add a new signal to the 
catch list. A signal can be a 
name or number. 

List of the signals that dbx 
does not catch. 

Add a signal, signal, to the 
ignore list. 

Set a breakpoint at the 
specified source line. The 
breakpoint is conditional if 
the variable, var, is 
specified. 

Set a conditional breakpoint 
at the specified source line. 

Set up to stop execution 
when the specified 
procedure, proc, is entered. 

Set a breakpoint in the 
specified procedure. The 
breakpoint is conditional if 
the variable, var, is 
specified. 

Set a breakpoint at the 
current source line. 

Set a conditional breakpoint 
in the specified procedure. 



Table 9-1. Commands for Setting Breakpoints 



c 



c 



( 
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Syntax 



Select this command to.. 



stop if exp 



stop var 



syscall 

syscall catch call 
syscall ignore call 
syscall catch return 
syscall ignore return 



syscall catch call syscall.. 



syscall ignore call syscall... 



syscall catch return syscall.. 



syscall ignore return syscall., 



Set up program execution 
tracing, test the expression 
at each program line, and 
stop when it is true. 
(Execution will be very 
slow.) 

Set up to stop execution 
when the variable, var, 
changes. (Execution will be 
very slow.) 

Print the list of system calls 
in 4 sections. 



These four commands print 
individual sections of the 
4-section list that syscall 
prints. 

Make the named system 
calls breakpoint at the entry 
of the system call. 

Make the named system 
calls not breakpoint at the 
entry of the system call. 

Make the named system 
calls breakpoint at the 
return from the system call. 

Make the named system 
calls not breakpoint at the 
entry from the system call. 



Table 9-1. (continued) Commands for Setting Breakpoints 
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Syntax 



Select this command to.. 



syscall catch call all 



syscall ignore call all 



syscall catch return all 



syscall ignore return all 



trace 



trace var 



trace proc 



trace var Lnproc 



trace var at line 



trace var at line if exp 



Make all system calls 
breakpoint at the entry to 
the system call. 

Make all system calls not 
breakpoint at the entry to 
the system call. 

Make all system calls 
breakpoint at the return 
from the system call. 

Make all system calls not 
breakpoint at the return 
from the system call. 

Step through the program a 
line at a time without 
stopping. 

When the variable, var, 
changes, print its old and 
new values. (Execution will 
be very slow.) 

When the procedure, proc, 
is entered, print its 
arguments and its caller's 
name. 

Print the variable, var, 
when it changes in 
procedure, proc. 

Print the variable, var's, old 
and new values when the 
source line is reached. 

If the expression is true 
when the source line is 
reached, and the variable, 
var, has changed value, 
print the old and new 
values. 



c 



c 



Table 9-1. (continued) Commands for Setting Breakpoints 
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Syntax 



Select this command to., 



trace var in proc if exp 



when if exp {command-list} 



when at line [if exp] {command-list} 



when var [at line] [if expr] {command-list} 



when var [in proc] [if expr] {command-list} 



when in proc [if exp] {command-list} 



Print the variable, var, 
when it changes in the 
procedure proc, if the 
expression, ex/?, is true. 

Execute command-list on 
every line executed for 
which the expression, exp, 
is true. (Execution will be 
very slow.) 

Execute the specified 
command-list when the 
conditions are met. 

Execute the specified 
command-list when the 
conditions are met. 
(Execution will be very 
slow unless at line is 
specified.) 

Execute the specified 
command-list when the 
conditions are met. 
(Execution will be very 
slow.) 

Execute the specified 
command-list when the 
conditions are met. 



Table 9-1. (continued) Commands for Setting Breakpoints 
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9.1 Introduction 

When a program stops at a breakpoint, the debugger displays an 
informational message. However, before setting a breakpoint in a program 
that has multiple files, be sure that you're setting the breakpoint in the right 
file. 

To select the right procedure, follow these steps: 

1. Use the func command and specify a procedure name. This command 
moves you to the file that contains the specified procedure (see Chapter 
8, "Controlling Your Program"). 

2. List the lines of the procedure. Use the list command (see Chapter 8). 

3. When you see the procedure or line you want, use a stop command to set 
a breakpoint. 

You can use the dbx variable $showbreakaddrs to verify exact breakpoint 
placement. For example: 

set $showhraakaddrs=l 

shows the address of each breakpoint placed in the code each time it is 
placed. Removal of the breakpoints is not shown. If multiple breakpoints are 
placed at one location only, one of the placements is shown. Since 
breakpoints are frequently placed and removed by dbx, the volume of output 
can be annoying when tracing. 

This chapter describes the stop, trace, and when commands, which set up 
breakpoints and tracing, but do not begin or continue program execution. 
Each command takes several optional arguments (clauses); two that appear 
repeatedly are the variable and if expression clauses. They are explained 
in the following paragraphs. 



o 



c 



( 
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9.1.1 The variable Clause 

The variable clause turns the command into a conditional command. The 
condition is "has the variable value changed?". When variable is used, it 
may be either a variable or an expression. 

If a variable is given, that variable is inspected at "appropriate" points. If an 
expression is given, that expression is assumed to be a pointer to a 32-bit 
value and the value-pointed-at is inspected at the appropriate points. An 
appropriate point is either: 

• at specific locations in the program (if at line) 

• at every instruction in a given function (if in procedure) 

• at every instruction (execution will be very slow). 

If variable has changed, then the result of the condition test "has the 
variable's value changed?" is true. Otherwise, the result of the test is false. 
The old and the new values are printed. 



9.1 .2 The if expression Clause 

The if expression clause turns the command into a conditional command. 
The expression is evaluated at the same points as mentioned for variable 
and evaluates to true and false. 



9.1.3 Combining the variable and if expression 
Clauses 

If you use both variable and if expression, the overall test evaluates to 
true only if both evaluate true. 

The stop command, for example, stops execution of the process when the 
if clause is true (if present) and the variable has changed (if present). 
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9.2 stop (breakpointing) 

The syntax for the stop command is at the beginning of this chapter. 
Examples include: 

stop in funcf 

stop at "fil#.c":27 

stop at 38 

b 38 

stop in funcz if x==0 

Interactive function calls provide a powerful way to set breakpoints. 

For example, function foo has a C string argument s and an integer 
argument L Then to stop when s is "abc" and i is 24, issue the command: 

stop in foo if i = 24 && strcmp ( "abc" , s) = 

This only works if the function strcmp(3C) is linked into the program you 
are debugging. 



9.3 Tracing (trace) ( 

The trace commands print information about the process when the trace 
conditions are satisfied, but program execution continues. The syntax for 
tracing is given at the beginning of this chapter. 

The trace command steps through the program a line at a time without 
stopping. This command is useful with edge{\\ as edge shows the source 
code with a green bar on the line executing as dbx steps through it. 



Examples include: 



trace funcf 
trace z 



C 
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9.4 Writing Conditional Code {when) 

The when command is similar to stop except that rather than stopping when 
the conditions are met, the command-list {dbx commands separated by 
semi-colons) is executed. If one of the commands in the list is stop (with no 
operands), then the process will stop when the command-list is executed. 

Examples are: 

when in fun ex { trace z } 

when at "file. c": 27 if z=2 {print y} 



9.5 Stopping at Signals (catch and ignore) 

The catch command lists the signals that dbx catches or specifies a signal for 
dbx to catch. If a child in the program encounters a specified signal, dbx 
stops the process and gives you control. 

You can use signal names and numbers as listed on the signal(2) man page. 
You can abbreviate signal names by omitting the "SIG" portion, dbx ignores 
case on the signal names. 

Note: dbx ignores SIGSTOP, SIGTSTP, SIGCONT, SIGTTIN, and 
SIGTTOU in this version since handling them would lead to 
problems in dbx as presently coded (they are used for "Z handling 
in csh). Using dbx to debug a program (such as a shell) that 
manipulates the above signals will not work well. 

The syntax: 

catch [signal] 

adds a new signal to the catch list. A signal is specified as a name or a 
number. For example, the interrupt signal is named INT, SIGENT, or 2. A 
process does not see this signal directed at it until 1) the signal comes to dbx 
and the process is stopped, and 2) the process is continued. If the process has 
not declared a signal handler for a signal, the process does not see the signal 
when it is continued. 
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The syntax: 

ignore [signal] 

adds a signal, signal, to the ignore list. A signal is specified as a name or a 
number. For example, the interrupt signal is named INT, SIGENT, or 2. A 
process sees this signal when directed at it by itself or by another process. 
The process responds to the signal just as if dbx were not present. A SIGINT 
signal at the keyboard is seen by dbx and it interrupts dbx (it is also sent to 
the process(s) being debugged). Keyboard-generated signals are seen by the 
whole process group (i.e., the IRIX process group, not the dbx process 
group). 

Debugging a program that attempts to catch signals can be awkward if you 
catch the signal in dbx. For example, if program P wants to catch SIGFPEs 
and you issue the command: 

catch sigfpa 

then you must, after dbx sees the signal ignore sigfpe allow program P to 
see the signal when you issue the command: 

cont sigfpe 

Having ignored the signal, you have to get control in dbx again (the best 
way would be to set breakpoints before doing the cont) to re-do the catch 
sigfpe if you wish to catch floating-point exceptions. 

Examples are: 

catch 2 
ignore INT 



C 



C 



C 
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9.6 Stopping at System Calls (syscall) 

The syscall command prints the list of system calls. The syntax is listed in 
the beginning of this chapter. 

The list of system calls is printed in four sections. System calls may be 
caught (breakpointed) at the time the call is made, or when it is about to 
return. The syscall command prints the system calls in the four sections: 

1. caught at call 

2. ignored at call 

3. caught at return 

4. ignored at return 

The system calls are all listed in lusrlincludelsys.s. In all syscall commands, 
case is ignored when checking system call names. Thus you can use lower 
case in these commands. 

The syscall catch call syscall... command makes the named 
system calls breakpoint at the entry of the system call. A particularly useful 
setting is: 

syscall catch call exit 

which will breakpoint the entry to exit(). Thus, if the program is about to 
terminate, you can do a stacktrace before the termination to see why exit() 
was called. Examples include: 

syscall 

syscall catch call exit 

syscall catch return read 
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c 



( 



10. Examining Program State 



This chapter describes how to examine a program's state by: 

• printing stack traces 

• moving up and down the activation levels of the stack 

• printing variable values 

• printing register values 

• printing information about the stack trace activation levels 

• using interactive function calls 
Examples: 

where 

up 4 

down 

printf "8. If %d\n" , fv2, ival 

print $pc 

dump . 

ccall func (y, 3) 
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Syntax 



Select this command to... 



ccall func(argl f arg2,...,argri) 
down [num] 

dump 

dump [proc] 

dump . 

print [expl...expN] 

print "stringer [expl , ... r expN] 

print regs 
up [num] 



where 



Call a function with the 
given arguments. 

Move down the specified 
number of activation levels 
in the stack. The default is 
one level. 

Print variable information 
about the current 
procedure. 

Print variable information 
about the procedure, proc, 
which must be active. 

Print variable information 
for all procedures currendy 
active. 

Print the value of the 
specified expressions. 

Print the value of the 
specified expressions in the 
format specified by the 
string, string. 

Print the current values of 
all current registers. 

Move up the specified 
number of activation levels 
in the stack. The default is 
one 
level. 

Print a stack trace. 



c 



Table 10-1. Commands to Examine a Program's State 
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10.1 Doing Stack Traces {where) 

The where command prints stack traces. Stack traces show the current 
activation levels (procedures) of a program. This command doesn't trace 
variables. For example: 

where 
t 

The t is an alias for where. 



10.2 Moving In the Stack {up and down) 

The up and down commands move up and down the activation levels in the 
stack. These commands are useful when examining a call from one level to 
another. You can also move up and down the activation stack with the June 
command. For a definition of activation levels, see "Activation Levels" in 
Chapter 2. For example: 

up 
up 2 
down 3 
down 



10.3 Printing {print and printf) 

The print command lists the value of one or more expressions. You can also 
use print to display the program counter and the current value of registers 
(see the following section, "Printing Register Values," for details). 

The printf command lists information in a format you specify and supports 
all formats of the IRIX printf command except %s. For a list of formats, see 
the printf(3S) man page in the IRIX Programmer's Reference Manual. For 
example, you can use printf 'in dbx when you want to see a variable's value 
in a different number base. 
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The command alias list has some useful aliases for printing the value of 
variables in different bases: octal (po), decimal (pd), and hexadecimal (px). 
The default number base is decimal. See "Creating Command Aliases" in 
Chapter 6 for more information. Examples are: 

print Zp->X[a] .bval 

printf "%8.1£\n",£val f 

printf "8. If %d\n",£v2,ival \ 

regs command" 



10.4 Printing Register Values (printregs) 

The printregs command prints register values, both the real machine register 
names and the software (from the include file regdefs.h) names. A prefix 
before the register number specifies the type of register. The prefixes used 
and their meanings are shown in the following table. 



Prefix Register Type 



$r machine register | 

$f floating point ^ 

$d double precision floating point 

$pc program counter value 



Table 10-2. Register Prefixes 



You can also specify prefixed registers in the print command to display 
a register value or the program counter. For example, typing: 

print $r3 
print $pc 

prints the values of machine register 3 and the program counter, 
respectively. Set the dbx variables $hexints and $hexouts to 1 to specify that 
the listing uses hexadecimal. 



( 
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10.5 Printing Activation Level Information 
(dump) 

The dump command prints information about activation levels. For 
example, this command prints values for all variables local to a specified 
activation level. To see what activation levels you have in your program, 
use the where command to do a stack trace. Examples include: 

dump 

dump funcf 

dump . 



10.6 Interactive Function Calls (ccall) 

The interactive function call, ccall, calls a function (with arguments, if 
given). Regardless of the language the function was written in, the call is 
interpreted as if it were written in C, and normal C calling conventions are 
used. The ccall command is particularly suited to procedures or functions 
that do not return a value. For example: 

ccall myfunc(x,2) 

You can call functions that do return a value as normal expressions. For 
example, to call the function/, which returns an integer (taking integer, 
double, and string arguments), and shift the results by two bits, type: 

print £(1,3.0, "a value") « 2 

If there is a breakpoint in a function called interactively, the value returned 
by the function is lost and any computation (for example, in an expression) 
following the function call is ignored. You can debug a function by setting 
breakpoints and calling it interactively. 

You can use string arguments with ccall, for example: 

print strcmp ("abed" , strp) 
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In addition, you can also have breakpoints in a function called interactively. 
It is up to you to eventually return. Any stack trace (where command) done 
while stopped in a routine executed interactively shows functions up to the 
interactive call with a line: 

<stopped in interactive call> 

as the end marker of the local interactive call stack. 

Interactive calls nest properly. This means that if you have one or more 
breakpoints in a function, and you call that function repeatedly, each 
interactive call is "stacked" on top of the previous call. Use the where 
command to report on the depth of nesting, if applicable. 

To unstack the calls, complete the call (cont, return, next, or step) as many 
times as necessary, or rerun the program being debugged. Unfortunately, 
there are no other ways to unstack the interactive call(s). 

Your breakpoints in functions called interactively do not respect the nesting. 
This can cause confusion if you attempt to have various breakpoints at 
different nesting levels. Breakpoints are all effectively at one level, and are 
always active. 

Only one level of activation stack is visible at a time; in an interactive call 
the stack trace of the hidden levels is invisible to you and to dbx. This can 
provoke: 

<variable> is not visible 

messages if you are actively tracing. For example, suppose you are in foo() 
and a "stop in foo if z==5" command is in effect. You do an interactive call. 
Delete such a "stop" to stop the messages, and re-enter the "stop" once out 
of the interactive call. 

Note: Structure and union arguments to, and structure and union returns 
from a function are not supported. 



c 



c 



c 
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11. Debugging at the Machine Level 



This chapter explains how to debug at machine level by: 

• setting breakpoints 

• executing single lines of code 

• tracing variables 

• printing the contents of memory addresses 

• disassembling the source code 

Additional information is in Chapter 4, "Expressions and Precedence." 
Examples: 

$pc-40/10i 

&z/8x 

$sp/20X 

stopi at 0x400abc 

nexti 

stepi 
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Syntax 



Select this command to.. 



addr/<countXmode> 



addr/ count L valmask 



conti sig 



conti in proc 



conti to addr 



conti sig to addr 



conti sig in proc 



next i [integer] 



Print the contents of the 
specified address, addr, for 
the specified count, count. 
The modes are listed at the 
end of this chapter. 

Print those words at addr 
that match val after 
ANDing with mask. 
Examine count words for a 
match. 

Send the specified signal, 
sig, and tell dhx to 
continue. 

Tell dbx to continue until 
the beginning of the 
specified procedure, proc. 

Tell dbx to continue until 
reaching the specified 
address, raddr. 

Tell dbx to continue until 
reaching the specified 
address, addr, then send the 
specified signal, sig. 

Tell dbx to continue until 
reaching the beginning of 
the specified procedure, 
proc, then send the signal, 
sig. 

Step over the specified 
number of machine 
instructions. The default is 
one. This command does 
not step into procedures. 



c 



c 



Table 11-1. Machine Level Debugging Commands 
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Syntax 



Select this command to... 



step! [integer] 



stopi at 
stopi at addr 

stopi at addrLf exp 



stopi var at 



stopi[var7 at addr 



stopi [var] at addrLf exp 



stopi if exp 



Step the specified number 
of machine instructions. 
This command steps into 
procedures even if no 
source, symbols, or line 
numbers are present. The 
default is one. 

Stop dhx at the current line. 

Stop dhx at the specified 
address, addr. 

Stop dbx at the specified 
address only if the 
expression, exp, is true. 

Stop dhx at the current line 
and check to see if the 
specified variable, var, has 
changed. If so, dbx prints 
the old and new values of 
the variables. 

Stop dbx at the specified 
address, addr, and check to 
see if the specified variable, 
var, has changed. If so, dbx 
prints the old and new 
values of the variables. 

Stop dbx at the specified 
address only if the 
expression, exp, is true. If 
stopped, dbx checks to see 
if the specified variable, 
var, has changed. If so, 
dbx prints the old and new 
values of the variables. 

Stop dbx if the specified 
expression, exp, is true. 



Table 11-1. (continued) Machine Level Debugging Commands 
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Syntax 



Select this command to... 



stopi var if exp 



stopi in proc 



stopi var in proc 



stopi in proc if exp 



stopi var in proc if exp 



tracei var 



tracei [var] at addr [if exp] 



tracei [var] in proc [if exp] 



Stop dbx if the specified 
variable, var, changes and 
the specified expression, 
exp, is true. 

Stop dbx at the beginning 
of the specified procedure, 
proc. 

Stop dbx in the specified 
procedure, proc, when the 
specified variable, var, 
changes. 

Stop dbx in the specified 
procedure, proc, if the 
specified expression, exp, is 
true, dbx checks exp before 
var. 

Stop dbx in the specified 
procedure, proc, when the 
variable, var, changes and 
the expression, exp, is true. 
dbx checks exp before var. 

Trace the variable at each 
machine instruction. 
Execution will be very 
slow. 

Trace the variable in 
machine instructions. 

Trace the specified variable 
in machine instructions. 
Execution of proc will be 
very slow. 



Table 11-1. (continued) Machine Level Debugging Commands 
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11.1 Setting Breakpoints (stopi) 

The stopi commands set breakpoints in machine code. These commands 
work in the same way as the stop at, stop i, and stop if commands described 
in Chapter 9, "Setting Breakpoints." There are two exceptions. The stopi 
command steps in units of machine instructions instead of in lines of code. 
Also, the stop at command requires an address rather than a line number. 
See the earlier discussion of stop for details on these complex statements. 
For example: 

stopi at 0x434500 
stopi in funcx 

The second example stops at the first machine instruction in function/j^ac. 
A where command at the point of stop may yield an incorrect stack trace 
since the stack for the function is not completely set up until several 
machine instructions have been executed. This version of dbx does not know 
how to correctly report in complete stack frames. 



11.2 Continuing after Breakpoints (conti) 

The conti commands continue executing assembly code after a breakpoint. 
Turn to the beginning of this chapter for the syntax of this command. 



11.3 Executing Single Lines (step/ and nexti) 

The stepi and nexti commands execute a fixed number of machine 
instructions, as specified by exp. If you don't specify exp for stepi and nexti, 
dbx executes one machine instruction. If you do specify exp, dbx executes 
the machine instructions according to the following rules. 

• With stepi and nexti the program executes exp machine instructions, 
ignoring any comment lines interspersed among them. 

• With stepi, exp applies to the current procedure as well as procedure 
calls (jal mdjalr). The program stops after executing exp instructions. 
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• With nexti, exp applies only to the current procedure. The program 
stops after executing exp instructions in the current procedure, ignoring 
any instructions executed in procedure calls. 

• Use stepi and nexti to execute source lines after a breakpoint. 

You can use all dhx variables for $nextbreak and $stepinto with the stepi 
and nexti commands exactly as with the step and next commands. 



11.4 Tracing Variables (trace!) 

The tracei commands track changes to variables, one instruction at a time. 
The tracei commands work for machine instruction as the trace commands 
do for lines of source code. The tracei command traces in units of machine 
instructions instead of in lines of code. (See the discussion of trace in 
Chapter 9 for details.) For example: 

tracei x 



1 1 .5 Printing the Contents of Memory 

Entering values in the syntax shown below prints the contents of memory 
according to the specifications that follow. 

address/ count format 

Prints the contents of the specified address or disassembles the code 
for the instruction at the specified address. Repeat for a total of count 
addresses in increasing address. This might be termed the "examine 
forward" command. 

address ? count format 

Prints the contents of the specified address or disassembles the code 
for the instruction at the specified address. Repeat for a total of count 
addresses in decreasing address (the "examine backward" command). 



c 



c 
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address/count 'Lvalmask 

Examines count 32-bit words in increasing address. Print those 32-bit 
words which, when ORed with mask, equals vol. This command 
therefore searches memory for specific patterns. 

Repeats the previous examine command with increasing address. 

. ? Repeats the previous examine command with decreasing 
address. 



Command 


Examine command formats: 


i 


print machine instructions (disassemble) 


d 


print a 16-bit word in decimal 


D 


print a 32-bit word in decimal 


o 


print a 16-bit word in octal 





print a 32-bit word in octal 


X 


print a 16-bit word in hexadecimal 


X 


print a 32-bit word in hexadecimal 


L 


like X but use with val mask 


b 


print a byte in octal 


c 


print a byte as character 


s 


print a string of characters that ends 




in a null byte 


f 


print a single-precision real number 


g 


print a double-precision real number 



Table 11-2. Disassemble Commands 

For example, to print 20 disassembled machine instructions starting at 
the current pc-20, type: 

$curpc-20/20i 

To print 32-bit words starting at address 0x400200 whose least significant 
byte is hexadecimal ee (100 words are inspected), type: 

0x400200/100L Oxee Oxff 
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c 



c 



( 



12. Multi-Process Debugging 

This chapter explains multi-process debugging procedures, including: 

• listing available running processes 

• adding a process to the available pool 

• listing the available processes 

• selecting processes 

• suspending the active running process 

• resuming suspended processes 

• freeing processes from the dbx pool 

• returning freed processes to the operating system 

• terminating active processes 

• using forks and execs 

• debugging process groups 
Examples: 

addproc 1234 
kill 1234 
resume pid 3456 
showproc 
stop pgrp 
suspend pid 4365 
waitall 
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Syntax 


Select this command to... 


active [pid] 


Tell dhx which is the active 




process in the pool of dbx 




controlled processes, pid is 




the process identification 




number (PID#) of the 




process you want to select 




as active. If pid is not 




specified, dhx prints the 




currently active process id. 


addproc pid 


Add the specified process 




tothepoolofdfot 




controlled processes. 


delproc pid 


Delete the specified process 




from the pool of dbx 




controlled processes. 


kill 


Kill the active process. 


kill pid... 


Kill the active process(es) 




whose PIDs are specified. 


resume 


Resume execution of the 




program, and return 




immediately to the dbx 




command interpreter. 


resume signal 


Resume execution of the 




process, sending it signal, 




signal, and return 




immediately to the dbx 




command interpreter. 


showproc [pid\ all] 


Show processes currently 




available for debugging 




under dbx. If you use no 




arguments, dbx lists the 




processes it already 




controls. 


wait 


Wait for the active process 




to stop for an event 



c 



c 



Table 12-1. Multi-process Debugging Commands 



c 
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Syntax 



Select this command to.. 



waitall 



suspend 



suspend pid pid 



Wait for any process 
currently running to 
breakpoint or stop for any 
reason. 

Suspend the active process 
if it is running. If it is not 
running, do nothing. 

Suspend the process pid if 
it is running. If it is not 
running, do nothing. 



Table 12-1. (continued) Multi-process Debugging Commands 



12.1 Processes 

dbx provides commands specifically for seizing, stopping, and debugging 
currently running processes. When dbx seizes a process, it adds it to a pool 
of processes available for debugging. Once you select a process from the 
pool of available processes, you can use all the dbx commands normally 
available. 

Once you are done with the process, you can terminate it, return it to the 
pool, or return it to the operating system. 

Many commands now take a clause, pid p id (where pid is a numeric 
process id or a debugger variable holding a process id) at the end to make 
them apply to process pid. Commands that do this include: 



active 


edit 


readsyms 


use 


addproc 


file 


resume 


wait 


assign 


func 


return 


what is 


catch 


goto 


showproc 


when 


cont[i] 


ignore 


status 


where 


delete 


kill 


step[i] 


whereis 


delproc 


next 


stop[i] 


which 


directory 


print 


suspend 




down 


print £ 


trace [i] 




dump 


print r eg s 


up 
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Using the pldpid clause means you can apply a command to any process 
in the process pool even though it is not the active process. 

Debugger variables help write multiple-process scripts independent of 
process id: 

• $lastchild is always set to the process id of the last child forked or 
sproced. 

• $pidO is always set to the process id of the given process. 



12.2 Listing Available Processes (showproc) 

Use the showproc command to list the available processes. The showproc 
command can take either of two optional arguments: zpid (process 
identification number, PID#), or the word all. If you specify a PID number 
with showproc, dhx lists the status of the specified process. 

If you use showproc with the command argument all, dbx lists all the 
processes it controls as well as all those processes it could control but that 
are not yet added to the process pool. 

If you use showproc without command arguments, dhx lists the processes it 
already controls (currently in the process pool). 

For example: 

showproc 2355 
showproc all 



12.3 Adding a Process (addproc) 

To add a process to the process pool, use the addproc command. The 
argument for the addproc command is the PID # of the process that you 
want to add. Adding the process to the dbx process pool automatically stops 
the process. 
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c 



c 



( 



For example: 

addproc 345 



12.4 Removing a Process (de/proc) 

To remove a process from the process pool, use the delproc command. The 
argument for the delproc command is the PID # of the process that you want 
to delete. Removing the process from the dbx process pool automatically 
stops the process. 

For example: 

delproc 134 385 
dalproc pld 37 
delproc 



12.5 Selecting a Process {active) 

dbx allows you to seize control of a number of processes. By default, dbx 
commands apply only to the active process. To select a process from the 
process pool to be the active process, use the active command. The 
argument to the active command is the PID# of the process in question. If 
you do not specify an argument, dbx lists the currently active process. 

For example: 

active 2355 
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12.6 Suspending a Process {suspend) 

Adding a process to the dbx pool of controlled processes does not 
automatically stop the process. You can stop a dbx controlled process only 
if it is the currently active process (use the active command). Use the 
suspend command to stop the currently active process. 

For example: 

suspend pid 2355 
suspend 



( 



12.7 Resuming a Suspended Process 
(resume) 

To resume execution of a suspended dbx controlled process, use either the 

cont command or the resume command, resume returns immediately to the 

dbx command processor. If you use cont, you do not get the dbx command ^ 

interpreter back until the program encounters an event (e.g., a breakpoint). I 

The resume command can be very useful if you are debugging more than 
one process. With resume, you are free to select and debug a process while 
another process is running. The argument for the resume command is 
signal. 

For example: 

resume pid 28 
resume 



12.8 Waiting for a Resumed Process (wait) 

To wait for a process to stop for an event (such as a breakpoint), use the wait 
command. This is useful after a resume command. Also see waitall, later in 
this chapter. 



1 2-6 dbx Reference Manual IRIS-4D Series 



For example: 

wait 

wait pid 347 



12.9 Freeing a Process (de/proc) 

To free a process from the control of dbx, use the delproc command. The 
argument for this command is the PID # of the process. For example: 

dalproc 2355 



12.10 Killing a Process (kill) 

To kill a process in the process pool while in dbx, you can use the kill 
command. For example: 

kill 2355 



12.11 Forks 

When a program forks and starts another process, dbx allows you to add that 
process to the process pool. You can set the variable $promptonfork to a 1 
or 2. 

If $promptonf br k-1 , when a program forks, dbx asks if you want to add the 
new process to the process pool. If you leave $promptonfork set to zero (the 
default), dbx ignores the process created by the fork. 

If $promptonfork=2, new forked processes are automatically added to the 
process pool. 
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c 



Consider a program named fork, that contains these lines: 

main ( argc , argv ) 
int argc; 
char *argv; 

{ 

int pid; 

if ((pid - fork()) == -1) { 

perror ("fork") ; 
} else if (pid == 0) { 

print f ("childO); 
} else { 

print f (" parent 0) ; 
} 
} 

If you set: 

$prompton£ork=l 

and run fork under dhx, the system prompts you to add the new process to 
the process pool. 

If you set: 

$promptonfork-2 I 

and run fork under dhx, the new process is automatically added to the pool, 
and both the parent and child processes stop executing at the fort 

When $promptonfork is zero, dhx doesn't stop at forks. 



12.12 Execs 

An exec is a call from within a program that executes another program. 
During an exec, the first program gives up its process number to the program 
it executes. You can use dhx to follow an exec. 



c 
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Consider the programs execl.c and exec2.c: 



main ( ) 
{ 



main ( ) 
{ 

} 



printf("in execl\n"); /* 

* Invoke the "exec2" program 
*/ 

execl ("exec2", "exec2", 0); /* 

* We'll only get here if execl () fails 
*/ 

perror ("execl") ; 



print f ("in exec2\n"); 



If you run execl under dbx, the system pauses to reread the symbolic 
information. Enter the dbx command, cont, to continue executing, now 
executing execl. 



12.13 Process Group Debugging 

The process group facility allows a group of processes to be operated on 
simultaneously by a single dbx command. This is far more convenient to use 
when dealing with sproced processes than issuing individual resume, 
suspend, or breakpoint setting commands. 

This facility was created to deal more conveniently with parallel programs 
created, for example, by the Power FORTRAN Accelerator (PFA). When 
debugging such code and before running the program, be sure to: 

s&t $mp__program=l 

For $mp_program: 

• if (the default), sproc is treated like fork. 

• if 1, sproc is treated specially. The children are allowed to run; they will 
block on multi-processor synchronization code emitted by mp 
FORTRAN code (if $mpj?rogram=l, mp FORTRAN code is easier to 
work with). 
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Whenever a process sprocs, if the child is added to the process pool, the 
parent and child are added to the group list as well. The group list is simply 
a list of processes. 

If the pgrp clause is added to the end of an applicable command (delete, 
next[i\, readsyms, resume, stop[i], status, suspend, trace[i], or when), the 
command is applied to all the processes in the group. 

If $groupforktoo is 1, then forked processes are added to the group 
automatically just as sproced processes are. 

The commands: 

stop {operands) pgrp 
trace {operands) pgrp 
when {operands) pgrp 

each add to the group history. With these commands, you can add 
breakpoints to multiple processes with a single command. This group 
history is a numbered list that showpgrp shows. 

The command: 

delete int pgrp 

deletes the history for group number int. Thus you can delete breakpoints 
from multiple processes with a single command. 

Breakpoints set on the process group are recorded both in the group and in 
each process. Deleting breakpoints individually (even if set via a group 
command) is allowed. 

The following commands are usable only on the processes in the group list. 

addpgrppzd... 

Adds the process ids specified to the group list. Only processes in the 
process pool can be added to the group list. 

delpgrp/jj'dL. 

Deletes the process ids specified from the group list. 

showpgrp 

Shows the group process list and the group breakpoint list. 
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c 






c 



12.14 Waiting for Any Running Process 
{wait all) 

To wait for any process currently running to breakpoint or stop for any 
reason, use the waitall command. It waits for all running processes in the 
process list, not just those in the group list. It does not make the process that 
stops first the active process. 

Normally, you would use this command after resume pgrp or resume. 

For example: 

waitall 



12.15 Multi-Process Debugging Examples 

The following pages contain examples for: 

• window process debugging 

• complex multi-process debugging 
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12.15.1 Window Process Debugging 

A process that calls winopen() forks unless foreground() is called. To debug 
such a process, try the following script 

set $pimode = 1 

# ensure the child is added to the pool 
set $promptonfork=2 

# run up thru fork() 
run 

# assume we have stopped at the winopen() fork() 
set $wpid = $lastchild 

# set the interesting process as the one commands apply to 
active $wpid 

# now can "cont" the process, or set breakpoints, or ? 
# 

# A script is a good place to set breakpoints, as breakpoints 

# set in the child are forgotten when you re-run the given 

# process. Remember that control-c (and the edge INTERRUPT 

# menu item) affect only dbx, not the child process we are 

# continuing. Use "suspend" to halt the window process. 



12.15.2 Compiex Multiple Process Debugging 

To debug a multiple process, try the following script. This script assumes 
you know ahead of time the sequence of operations of interest. You might 
try using the record and unrecord commands to save an interactive session 
which "got to the right point" as the basis for a script such as the one that 
follows. 

You can "continue" only one process. You can "resume" several processes 
at a time with: 

resume pgrp 

Or, you can resume several processes to run simultaneously with the 
commands in sequence. For example: 

resume pid 100 
resume pid 101 

You can see you are stopped at a breakpoint only when you "wait" for a 
process. 
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c 



c 



Assume that you want to control all children: 

set $pimode = 1 

# ensure that the child is added to the pool 
set $promptonfork=2 

# run up thru fork() 
run 

# assume we have stopped at the fork() 
set $chldl = $lastchild 

# run to exec(), then assume fork is next 
cont pid $chldl 

cont pid $chldl 

# on fork note process id 
set $chld2 = $lastchild 

# Set breakpoints in the program and so on. 

# Now can "cont" the process, or set breakpoints, or ? 

# Remember that control-c (and the edge INTERRUPT menu item) 

# affect only dbx, not the child process we are continuing. 

# Use "suspend pid <pid>" to halt process <pid>. 

# The script ends here. Begin interactive debugging. 

Now assume that you want to control only some children: 

set $pimode = 1 

# ensure that the child can be added to the pool 
set $promptonfork=l 

# run up thru fork() 
run 

n 

# n answered "Add child to process pool (n if no) ?" 

# For example, if this process is really a popen and 

# not interesting, continue executing the active process: 

# up through "interesting" fork, 
cont 

y 

# remember the pid 

set $childl = $lastchild 

# run up to another fork() 
cont pid $pidO 

# remember another child 
set $child2 = $lastchild 

# Set breakpoints in various procs. Func names, variables, 

# etc. are evaluated in context of the process named, 
stop at func7 pid $childl 

stop at func8 pid $child2 

# and so on. 

# and so on. Now can "cont" a process, or set breakpoints, 

# or ? Remember that control-c (and the edge INTERRUPT menu 

# item) affect only dbx, not the child process we are 

# continuing. Use "suspend pid <pid>" to halt process <pid>. 

# The script ends here. Begin interactive debugging. 
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c 



c 



Appendix A: dbx Command 

Summary 



Table A-l lists all commands (except for command line editing commands) 
and gives each command's alias, syntax, and brief description. For more 
information about a command, refer to the description of the command in 
the main part of this manual. 
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Command Alias Syntax 



Select this command to: 



/ 



active 



addpgrp 



addproc 



alias 



assign 



catch 



ccall 



cont 



Iregex 



iregex 



Istnng 

lint 

\-int 

active [pid] 



addpgrp pid.. 



Search ahead in the code for 
the specified string. 

Search back in the code for 
the specified string. 

Specify a command from 
history fist. 

List the active process; pid 
is the process id number. If 
no pid , list the currently 
active process. 

Add the process ids 
specified to the group list. 
Only processes in the 
process pool can be added to 
the group list. 



addproc pid 


Add specified process to the 




pool of dbx controlled 




processes. 


alias [name 


List all existing aliases, or, 


(argl....argn) 


if or "j?. define a new alias. 


"string"] 




assign expl = 


Assign the specified 


exp2 


expression to a specified 




program variable. 


catch [signal] 


List all signals that dbx 




catches, or, if org, add a 




new signal to the catch list. 


ccall func 


Call a function with given 


(argl,...argn) 


arguments. 


cont 


Continue executing a 


cont to proc 


program after a breakpoint. 


cont to line 




cont signal 




to line 




cont signal 




mproc 





c 



^ 

c 
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Command Alias Syntax 



Select this command to: 



conti 



corefile 



delete 

delpgrp 
down 



conti signal 


Continue executing 


conti to addr 


assembly code after a 


conti in proc 


breakpoint 


conti signal 




to addr 




conti signal 




in proc 




corefile 


Display the name of the core 


corefile core 


file; if the corefile is 




currently used by dbx, 




display program data. If 




core, identify corefile name, 




as in that core file for 




program data. 


delete expl,... 


Delete the specified item 


expn 


from the status list. 


delete all 




delpgrp pid... 


Delete the process ids 




specified from the group list. 


down [exp] 


Move down the specified 



number of activation levels 
in the stack (default, one 
level). 





dump . 


about proc. Print global 
variable information for all 
procedures (.). 


edit 


edit {file] 


Call an editor from dbx. 


examine addr 


addr/<cnt><mode> 


Print the contents of the 
specified address or 
disassemble the code for the 
instruction at the specified 
address. 


file e 


file [file] 


Print the name of the current 
file or specified file. 


func f 


func 


Move to the specified 




funce^p 


procedure (activation level) 




func proc 


or print the current 
activation level. 
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Command 


Alias 


Syntax 


Select this command to: 


givenfile 




givenfile 
givenfile name 


Set program to debug, as in 
running processes and read 
in name's symbol table. 


goto 


g 


goto line 


Go to the specified line. 


help 


? 


help 


Print a list of dhx 
commands. 


history 


h 


history 


Print a list of the previous 
commands issued (default is 
20). 


ignore 




ignore signal 


List all signals that dbx does 
not catch, or add specified 
signal to ignore list. 


kill 




kill [pid...] 


Kill the active process(es). 


list 


li 


list 

list [expiint] 

fist [exp] 


List the specified lines 
(default is 10). 


next 


n 


next [int] 


Step over the specified 
number of lines (default is 
1). Does not step into 
procedures. 


nexti 


ni 


nexti [int] 


Step over the specified 
number of machine 
instructions (default is 1). 
Does not step into 
procedures. 


playback 
input 


Pi 


playback input 
file 


Replay commands saved 
with the record input 
command in a text file. 


playback 
output 


po 


playback output 
file 


Replay dhx output saved 
with the record output 
command in a text file. 


print 


P 


print expl,... 
expn 


Print the value of the 
specified expression. 


printf 


pd 


printf "string" 
exp 1,... expn 


Print the value of the 
specified expression, using 
C string formatting. 


printregs 


pr 


printregs 


Print all register values. 



( 



c 



c 
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Command 


Alias 


Syntax 


Select this command to: 


quit 


q 


quit 


Exit dbx. 


record 


ri 


record input 


Record all commands typed 


input 




file 


to dbx. 


record 


ro 


record output 


Record all dbx commands. 


output 




file 




resume 




resume 


Resume execution of the 






resume signal 


program (send it signal), 
and return immediately to 
dbx. 


return 




return \proc] 


Continue executing until the 
procedure returns. If no 
procedure specified, dbx 
assumes the next procedure. 


run 




run [argl...argn] 


Run your program. 



set 



sh 
showpgrp 

showproc 



rerun 


Run program again, using 


[argl...argn] 


the same arguments 


[<filel] [>file2] 


specified to the run 




command. 


set 


For the existing dbx 


set var = exp 


variables and their values, 




assign a value to a variable, 




or define a new variable and 




assign a value to it. 


sh [sh cmd] 


Call a shell from dbx or 




execute a shell command. 


showpgrp 


Show the group process list 




and the group breakpoint 




list. 



showproc [p/dlall] 



Show processes currently 
available for debugging. 
With no arguments, list the 
processes under control. 
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Command Alias Syntax 



Select this command to: 



source 



source [file] 



status 



status 



Execute dbx commands 
from the specified file. If no 
file specified, dbx assumes 
that you want the file 
created with the record 
input command. 

Print a list of currently set 
breakpoints, record 
commands and traces. 



step 


s 


step [int] 


Step the specified number of 
lines (default is 1). This 
command steps into 
procedures. 


stepi 


si 


stepi [int] 


Step the specified number of 
machine instructions 
(default is 1). This 
command steps into 
procedures. 


stop 


b 


stop [var] at 


Set a breakpoint at the 




bp 


stop [var] at line 
stop [var] in proc 
stop [var] if exp 
stop [var] at line 

if exp 
stop [var] in proc 

if exp 


specified point. 


stopi 




stopi [var] at addr 


Set a breakpoint in machine 






stopi [var] in proc 


code at the specified point. 






stopi [var] if exp 








stopi [var] at addr 








if exp 








stopi [var] in proc 








if exp 




suspend 




suspend 


Suspend the active process 






suspend pid 


or process pid if running. If 
it is not running, do nothing. 



c 
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Command 


Alias Syntax 


Select this command to: 


syscall 


syscall 


Print list of system calls. 


trace 


tr trace var 

trace var at line 
trace var in proc 
trace var at line 

ifexp 
trace var in proc 

ifexp 


Trace the specified variable. 


tracei 


tracei var 


Trace the specified variable 




tracei var at oddr 


in the machine instruction. 




tracei var in proc 






tracei var at addr 






ifexp 






tracei var in proc 






ifexp 




unalias 


unalias aliasname 


Remove the specified alias. 


unset 


unset var 


Unset a dbx variable. 


up 


up [exp] 


Move the specified number 
of activation levels up the 
stack (default is 1). 


use 


use [a7ri dirl... 


Print a list of the source 




dirn] 


directories, or if directory 



wait 



wait 
waitall 



name given, use new 
directories for the previous 
list. 

Wait for the process (any 
current process) to stop for 
an event. 
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Command Alias Syntax 



Select this command to: 



whatis 



when 



where 



whereis 



which 



whatis var 

when [var] 

[ifexp] 

{command-list} 
when [var] at line 

[if exp] 

[command-list} 
when [var] in 
proc 

[ifexp] 

{command-list} 

where 
whereis var 
which var 



Print the type declaration for 
the specified name. 

Execute the specified dbx 
commands during 
execution. 



C 



Do a stack trace to show 
current activation levels. 

Print all qualifications of the 
specified variable name. 

Print the qualification of the 
variable name currently in 
use. 



Table A-1. (continued) Command Summary 
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Appendix B: Sample Program 



This program, anthrax.c, counts non-blank lines in a program. 
■ C Program: anthrax 

#include <stdio.h> 

struct line { 

char string [256]; 

int length; 

int linenumber; 

};typedef struct line LINETYPE; 
void printline () ; 

main(argc, argv) 



int 


argc; 




char 


**argv; { 






LINETYPE 


linel; 




FILE 


*fd; 




extern FILE 


*f open () ; 




extern char 


*fgets () ; 



if (argc « 2) { 

fprintf (stderr, "Usage sam f ilenameO) ; 

exit (1); 
} /* if */ 

fd = fopen (argv[l], "r") ; 

if (fd == NULL) { 

fprintf (stderr, "cannot open %s0, argvfl]); 

exit (in- 
version 3.0 Sample Program B-1 



} /* if */ 

/*loop through lines in a file and 
/*call a routine to print*/ 

/*blank lines along with line numbers, line lengths*/ 

while (f gets (linel . string, sizeof (linel . string) , fd) 
!= NULL) 

{ 

int i ; 

static curlinenumber =0; 

i = strlen (linel . string) ; 
if (i == 1 && linel. string[0] == '0) 
continue; /* don't count blank lines */ 

linel. length = i; 

linel . linenumber = curlinenumber++; 
Printline (&linel) ; 
} /* while */ 
} /* main */ 

void printline (pline) 

LINETYPE *pline; 

{ 

int i; /*dummy var entered to demo whereis cmd*/ 

i = 0; 

fprintf (stdout, "%3d. (%3d) %s", 

pline->linenumber, pline->length, pline->string) ; 

f flush (stdout); 
} /* printline */ 



C 






c 
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Appendix C: Questions and 

Problems 



Here are some of the most commonly asked dbx questions (and the 

answers): 

Q: How do I pass arguments to my program when using dbx? 
A: Use: 

run <argl> <argN> 
rerun <argl> <argN> 

For example, if you are using the debugger, type: 

run a 2 . <data . in >r©s . out 

To execute the same program in csh or the Bourne shell, type: 

myprog 2 2.0 <data . in >res . out 

dbx does not understand redirection other than the simple form presented in 
the example. It does not understand csh (>&) or Bourne shell (2>file) 
redirection. 



Version 3.0 Questions and Problems C-1 



Q: What use is it to look at the registers? Is this for the user or for hackers? 

A: The registers are not usually of interest. Those interested in learning the 
machine instruction architecture might want to examine the registers. 

However, you might be interested in the machine instructions at the point of 
a program fault. For this, you can do dissassembly. For example: 

$pc-40/20i 

prints 20 instructions disassembled, starting 10 instructions before the 
current program counter. 

Q: How do I add a child process to the process pool? 

A: Use $promptonfork. 

It is most useful to control a child process at the point of zfork or sproc. Do 
this with: 

$ prompt on f o rk=2 

if the program does very few forks and you wish to control them all. Or set: 

$prompfc©n£ork=i 

if you only wish to control some of the process forks. Then rerun the given 
process. 

Since it is somewhat tedious to rerun and respecify the necessary data to get 
to the "point of interest," try puting the needed commands in a script fine 
and executing that via & playback input (pi) command. 

Note that in most cases, once a child process begins running on its own 
(assuming $prornptonfork=0, for example), it is not very useful to intercept 
it. Nevertheless, you can intercept it and add it to the process pool by using 
addproc. For example: 

addproc 12345 



C 



( 
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Q: How do I look at the source of another function not in the current 
source file? 

A: Type: 

file filename 

For example: 

file myfile.f 

Then list, etc., will reference that file. 

Caution: Many commands reset the current source file as a side effect. For 
example, after doing "up" or "down," the current file will change. 

You can also use funcfuncname, for example: 

func my fun c 

If myfunc is active on the current activation stack, myfunc will become the 
current focus for the local variable and the current pc marker. Whether or 
not myfunc is active, the file containing myfunc source is the current source 
file for list commands, etc. 

As explained previously, various commands change the source focus. The 
command: 

file 

will print the current source focus. 

Q: How do I display a value in hex, octal , binary? 

A: For hex, use px. For octal, use po (currently, there is no method to print 
binary). 

For example: 

px a 

po b 

print f xx %o0',b 

print f x A %x0' ,a 
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Q: I got the message segmentation violation core dumped, what 
should I do with core? 

A: dbx can tell you where you bombed out. For example, suppose you have 
a program named a.out that died in the library function strcmp. 

Assuming the current directory contains a.out, core, and the source code of g- 
your program, type the IRIX command: I 

dbx a.out core 

The dhx command: 

t 

will show the stack traceback. And the dhx command: 

w 

will say "source is not available." This is true, since you don't have the 
source to the library function strcmp available. The dhx command: 

up 

will move up one level in the activation stack. If you called strcmp directly f 
with an invalid argument, the dbx command: 

w 

will then show your source code with the call to strcmp marked with ">". 

If strcmp was called by some other library routine, you may need to repeat 
up until w prints source code from your source file. 



c 
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Q: How do I find the address of a variable, array, procedure, or function? 

A: You can use print orpx to print the address. For example, suppose you 
have a variable named xl. Type: 

print &xl 

or 

px &xl 

which will print the address of xl. 

Q: How do I remove a breakpoint once it is set? 

A: Follow these steps: 

1. Type status to get a list of stop (breakpoint), trace, and when 
commands. 

2. Type delete <N>, where N is the entry number in the status list. For 
example: 

delete 7 
d 2 
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/command, 7-5 

! command, 1-2, 5-3 

$addrfmt, 6-5 

$casesense, 4-10, 6-5 

$charisunsigned, 6-5 

$ctypenames, 6-5 

$curevent, 6-5 

$curllne, 6-5 

$curpc, 6-5 

$datacache , 6-6 

$defaultin, 6-6 

$defaultout, 6-6 

$editor, 6-6 

$funcentrybyllnes, 6-6 

$groupforktoo, 6-7 

$hexchars , 6-7 

$hexin,6-7 

$hexints, 6-7 

$hexstrings, 6-7 

$hide_anonymous_blocks, 6-8 

$lastchild, 12-3, 12-4,6-8 

$lines variable, 5-3 

$lines, 6-8 

$llstwindow, 6-8 

$main, 6-9 

$maxstrlen , 6-9 

$mp_program, 6-9 

$naptime,6-9 

$nextbreak command, 11-6 

$nextbreak, 6-10 

$octin, 6-11 

$octints,6-11 

$page,6-11 

$pager, 6-11 

$pagewidth, 6-11 

$pagewindow, 6-11 

$pid, 12-3,6-11 

$pid0, 12-4,6-11 

$pimode,5-3, 6-11 

$printdata, 6-12 

$printwhllestep, 6-12 



$printwide, 6-12 
$print_exception_frame, 6-12 
$prompt, 6-12 

$promptonfork command , 3-2 
$promptonfork, 12-7, 6-13 
$regstyle,6-13 
$repeatmode, 6-13 
$showbreakaddrs, 6-13 
$steplnto command ,11-6 
$stepintoall, 6-14 
$tagfile, 6-14 
$visiblemangled , 6-14 
-g option, 3-1, 8-5 
16-bit word, 11-7 
32-bit word, 11-6 
; separator , 5-4 
? command, 1-2 7-5 



a (assign) command, 6-18 
activation level, 10-5 2-4 
activation level, 

down, 1-3 

go up, 1-7 
active command, 1-21-2 12-5 
active pid, 12-2 
add a process , 1 2-4 
add alias, 1-2 
add child process, 3-2 
add signal to ignore list, 1-4 
addpgrp command , 1 -2 
addpgrp, 12-10 
addproc command, 1-2, 12-4 
addproc, 12-2 
address of array, 3-5 
address of variable , 3-5 
alias command ,1-2 6-15 6-2 
alias examples, 6-24 
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alias, remove , 1 -7 
aliases, 

create, 6-15 

predefined, 6-18 
argument, pass, 3-1 
array address , 3-5 
assembly code breakpoint ,11-5 
assign a value, 1-5 
assign command , 1 -2, 8-8 
avoid common pitfalls, 2-7 



B 

b (stop at) command , 6-1 8 
begin at specified line, 8-7 
binary operators , 4-3 
binary value, display , 3-3 
bombed out, 3-4 
Bourne shell redirection, 3-2 
bp (stop in) command , 6-1 8 
breakpoint, 9-8 
breakpoint, 

continue after, 8-8 
remove , 3-5 6-30 
set, 1-6M1-5 
breakpoints, list, 1-6 
built-in aliases, 6-15 
built-in data types , 4-4 



c (cont) command , 6-1 8 
C language operators, 4-3 
C string format, 1-4 
C type-casts , 4-9 
call a function, 1-2 
call a shell, 1-5 
call an editor, 1-3 7-6 
call from a program , 12-8 
call, 

interactive, 10-5, 9-8 



case sensitivity , 4-10 

casts , 6-24 

catch command, 1-2, 9-9 

caught, 

at call , 9-1 1 

at return, 9-11 
ccall command, 1-£ 10-5 
change, 

source view, 7-4 

value of register, 8-8 

value of variable, 8-8 
chapter summary, 1-2 
check status , 6-29 
child process, 3-2 
code and source don't match , 2-7 
code missing , 2-7 
code, disassemble , 3-2 
command aliases, 6-15 
command file, 3-2 
command, execute ,1-8 
command-list, 1-8 
commands, record all, 1-5 
comments, 4-5 
compile a program , 3-1 
conditional code, write, 9-9 
confused listing , 2-7 
constants , 4-4 
constructor, 4-10 
cont command, 1-2 8-8 
conti command , 1-3, 11-5 
continue after breakpoint, 1 1 -5, 8-8 
continue execution, 1-2 1-5 
conventions , 1 -3 
core dump, 3-4 
corefile command, 1-3 3-6 
count non-blank lines, 2-1 
csh redirection, 3-2 
current source file , 3-3 
cursrcline, 6-5 
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d (delete) command, 6-18 

data types, 4-4 

dbxinit file, 3-2 

debug a new program , 2-6 

debug, 

a process group, 12-9 

a program, 2-5 

a simple program , 2-1 

FORTRAN, 12-9 

multi-processes, 12-11, 12-3 
debugger operations, 4-3 
decimal, 10-3 
declarations, type, 7-7 
define alias, 1-2 
define new variable , 1 -5 
delete alias, 1-7 
delete breakpoint , 3-5 
delete command, 1-3, 6-2, 6-30 
delete from status list, 1-3 
delete, 

a process, 12-5 

alias, 6-16 

status items, 6-30 

variables, 6-15 
delpgrp command, 1-3 
delpgrp, 12-10 
delproc command , 12-5, 12-7 
delproc, 12-2 
destructor, 4-10 
dir command, 7-3 
directory, specify, 7-3 
disassemble code ,11-6 
disassembly, 3-2 
display binary value, 3-3 
display hex value, 3-3 
display octal value , 3-3 
do a stack trace, 1-8 
documentation, 1-4 
down command, 1-3, 10-3 
dump command, 1-3, 10-5 



e (file) command, 6-18 

edit command, 1-3 

editor, 7-6 

end record session , 6-26 

end dbx, 3-7 

error, program , 3-2 

escapes , 4-2 

examine backward command ,11-6 

examine command, 1-3 

examine flow control, 2-6 

examine forward command ,11-6 

examine registers, 3-2 

example of a program , 2-1 

examples, alias, 6-24 

exec a process , 12-8 

execute another program, 12-8 

execute assembly code , 1 -3 

execute command , 1-8 

execute from a file, 1-6 

execute program , 1-5 

execute shell command, 1-5 

execute single line, 1 1-5, 8-4 

execution, 

continue, 1-2 1-5 
exit dbx, 1-5 
exit dbx, 3-7 

expression, print value, 1-4 
expressions , 4-3 



f (func) command, 6-18 
failure point location, 2-4 
fault, program , 3-2 
file command , 3-5 7-4 
find address, 3-5 
fork, 12-3, 12-7 
FORTRAN debugging, 12-9 
FORTRAN operators , 4-3 
free a process, 12-7 
func command , 1 -3 3-3, 7-4 
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function call, Interactive, 10-5 
function, call, 1-2 



invoke editor, 1-3 

invoke, 

a shell, 6-29 
an editor, 7-6 
dbx, 3-3 



( 



g (goto) command, 6-18 
givenfile command , 1-4, 3-6 
goto procedure, 7-4 
goto command , 1 -4, 8-7 
group debugging, process, 12-9 



j (status) command , 6-1 9 



H 

h (history) command, 6-18 
hardware registers, 4-6 
hed,5-3 

help command, 1-4 
help function, 3-7 
hex value, display, 3-3 
hexadecimal , 1 0-3 
history command, 5-3 
history editor, 5-3 
history list, 1-2, 1-4 



I 

if expression clause , 9-7 
ignore command, 1-4, 9-9 
ignore list, add signal, 1-4 
ignored, 

at call, 9-11 

at return, 9-11 
include file, 2-7 
input constants, 4-4 
input, 

playback, 6-28 

playback, 1-4 

record , 1 -5, 6-26 
instructions, step, 1-6 
interactive function call, 10-5, 9-8 



K 

keywords, 4-8 
kill a process, 12-7 
kill command, 1-4, 12-7 
kill, 12-2 



leave dbx, 1-5 
levels, 

activation , 1 0-5, 2-4 
li command, 6-19 
line, step over, 1-4 
lines, 

count, 2-1 

step, 1-6 
linked list, 6-24 
list active process, 1-2 1-2 
list breakpoints, 1-6 
list command, 1-4 7-5 
list processes, 1-5 
list signals caught, 1-2 
list signals not caught , 1 -4 
list source directories, 1-7 
list, 

available processes, 12-4 

source code, 7-4, 7-5 
listing is confused, 2-7 
locate the failure point, 2-4 
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lower-case names, 4-10 



overflow , 4-5 
overloaded operator, 4-10 



M 

machine code breakpoint , 1-6, 11-5 

machine code, trace, 1-7 

machine-level commands ,11-2 

manual conventions, 1-3 

memory, print contents, 11-6 

missing code, 2-7 

move down , 1 -3 

move in the stack , 1 0-3 

move to a procedure , 7-4 

move to procedure ,1-3 

move up activation level , 1 -7 

mp FORTRAN, 12-9 

multi-process debug commands, 12-2 

multi-process debugging, 12-11, 12-3 

multiple commands, 5-4 



N 

n (next) command , 6-1 9 
next command, 1-4, 8-4 
nextbreak command , 8-7 
nexti command, 1-4 11-5 
ni (nexti) command, 6-19 
no display of variables , 2-7 
non-blank lines, count, 2-1 



octal value, display, 3-3 

octal , 1 0-3 

on-line help, 3-7 

options to dbx, 3-3 

output, 

play back, 6-29 
playback, 1-4 
record , 1 -5, 6-27 



p (print) command, 6-19 

pass argument, 3-1 

pd (printf) command, 6-19 

pgrp, clause, 12-10 

pi (playback input) command, 6-19 

pid clause, 12-3 

pid, commands, 12-3 

play back input, 6-28 

play back output, 6-29 

playback input command , 6-2 

playback input , 1 -4 

playback output command , 6-2 

playback output, 1-4 

po (print var) command , 6-21 

pointer, 4-10, 9-7 

pool of processes, 12-3 

pool, add to , 3-2 

precedence, 4-3 

predefined alias, 6-17 

predefined variables, 6-5 



pri 
pri 
pri 
pri 
pri 
pri 
pri 
pri 
pri 
pr! 
pr 



about proc, 1-3 
activation level, 1-3 
breakpoints, 1-6 
command, 1-4, 10-3, 3-5 
file name, 1-3 
global information, 1-3 
history, 1-4 
qualifications, 1-8 
source directories, 1-7 
type declaration , 1 -8 

activation level, 10-5 
byte in octal ,11-7 
contents of memory ,11-6 
register values, 10-4 
symbolic names, 7-6 
type declarations, 7-7 
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word in decimal, 11-7 

word in hexadecimal, 11-7 

word in octal ,11-7 
printf command, 1-4 10-3 
printing, 10-3 
printregs command , 1 -4 
printwhilestep command , 8-5 
problems to avoid , 2-7 
procedure, move to, 7-4 
process exec, 12-8 
process pool, 12-7 
process, 

add, 1 -Z 12-4 

child, 3-2 

delete, 12-5 

fork, 12-7 

free, 12-7 

group debugging , 12-9 

identification number, 12-3 

Lrill A -A 10.7 
rviu , i — ij i c_-# 

list, 1-5 12-4 

pool, 12-4 

resume suspended, 12-6 

select, 12-5 

suspend, 12-6 

wait for resumed , 12-6 

wait for, 12-10 
program fault, 3-2 
program, run, 1-5 



q (quit) command, 6-21 
qualify variable, 4-2 
quit command, 1-5 
quitdbx, 1-5 
quit^x, 3-7 
quotations, 4-2 



R 

r (rerun) command, 6-21 
record command , 6-£ 6-25 
record input, 1-5 6-26 
record output command, 6-27 
record output, ^-5, 6-27 
redirection , 3-2 
register values, 10-4 
registers , 4-6, 8-8 
registers, 

examine, 3-2 

print values , 1 -4 
relevant documentation , 1 -4 
remove alias , 1 -7 
remove breakpoint , 3-5 
remove, 

a process ,12-5 

alias, 6-16 

breakpoint, 6-30 

status items , 6-30 

variables, 6-15 
replay commands, 1-4 
rerun command, 1-5, 3-1 
resume command, 1-$ 12-6 
resume, 12-2 
resume, 

after breakpoint, 11-5 

pgrp, 12-11 

suspended process, 12-6 
resumed process, wait, 12-6 
return command, 1-5 
return to command processor, 12-6 
ri (record input) command , 6-21 
ro (record output) command , 6-21 
run command, 1-5, 3-1 
run shell, 6-29 
running process, wait for, 12-10 
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S (next) command , 6-22 
s (step) command , 6-22 
sample program , 2-1 
search ahead , 1 -2 
search back, 1-2 
search, code, 7-5 
segmentation violation, 3-4 
select a process, 12-5 
select right procedure, 9-6 
set a breakpoint , 1 -6 
set breakpoint ,11-5 
set command, 1-5, 6-15, 6-3 
setting variables, 6-15 
sh command , 6-3 
shell, 

execute command , 1 -5 

invoke, 6-29 
showbreakaddrs command, 9-6 
showpgrp command , 1-5 
showpgrp, 12-10 
showproc command, *\-5, 12-4 
showproc, 12-2 
Si (nexti) command, 6-22 
si (stepi) command, 6-22 
SIGNAL, 8-8 
signals, ignore, 1-4 
single line execution ,11-5 8-4 
source (playback input) command , 
6-23 

source and code don't match , 2-7 
source code, 

list, 7-4 7-5 
source command , 1-6, 6-2$ 6-3 
source directories, print, 1-7 
source directory, 7-3 
source file, specify, 7-4 
source not available , 3-4 
source, look at, 3-3 
source-level debugger, 2-4 
specify, 

line to start, 8-7 

source directory, 7-3 



source file, 7-4 
sproc, 12-9 
stack trace, 1-8, 10-3 
stack traceback , 3-4 
stack, move , 1 0-3 
start another process, 12-7 
start at specified line , 8-7 
status command , 1-§ 6-29, 6-3 
status, 

check, 6-29 

delete , 6-30 
step command, 1-§ 8-4 
step over line(s) , 1-4 
step over machine instruction , 1-4 
stepi command , 1-6, 11-5 
stepintoall command, 8-5 
stop command , 1 -6i 9-8 
stop process , 1 -4 
stop, 

at signals, 9-9 

at system calls, 9-11 

currently running process, 12-3 
stopi command , 1-6, 11-5 
strcmp, 3-4 
strings , 4-2 
structures, 4-10 
suspend a process, 12-6 
suspend command, 1-6, 12-6 
suspend, 12-3 

suspended process, resume, 12-6 
symbol table information , 3-1 
symbolic names, 7-6 
syscall command , 1 -7, 9-1 1 
system call, stop at, 9-1 1 



t (where) command, 6-23 
terminate process, 12-7 
trace command , 1 -7, 9-8 
trace variable, 11-6 
trace, 
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stack, 1-8, 10-3 
traceback, stack, 3-4 
tracei command , 1 -7, 1 1 -6 
troubleshoot, 2-7 
type declaration, print, 1-8 
type declarations, print, 7-7 
type-casts , 4-9 



u 

unalias command, 1-7, 6-1 § 6-3 
unary operators, 4-3 
unrecord command, 6-26, 6-3 
unset command, 1-7, 6-1 5 6-3 
up command, 1-7, 10-3 
upper-case names, 4-10 
use command, 1-7, 7-3 
using this manual, 1-1 



w 

W (list lines of code) , 6-23 

wait command, 1-7, 12-6 

wait for resumed process, 12-6 

wait for running process, 12-10 

wait, 12-2 

waitall command, 12-10 

waitall, 12-3 

whatis command, 1-8, 7-7 

when command, 1 -8, 9-9 

where command, 1-§ 10-3 

whereis command, 1-8, 7-6 

which command, 1-$ 7-6 

wi (list assembly code) , 6-23 

window process debugging, 12-12 

write conditional code, 9-9 



( 



V 

value, change, 8-8 
values, print register, 10-4 
variable address, 3-5 
variable clause , 9-7 
variable names, 4-10, 4-2 
variable qualifications, 1-8 
variable, 

trace, 1-7, 11-6 

unset, 1-7 
variables won't display , 2-7 
variables, 6-15, 8-8 
variables, predefined , 6-5 
view function's source , 3-3 
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